README.md

August 20, 2026 · View on GitHub

trello.js

Type-safe Trello REST API client for Node.js and the browser.

English · Русский

Why trello.js

🔒 Fully typed. Every endpoint, parameter and response has a type, and none of them fall back to any.
✅ Runtime validation. Responses are checked by Zod 4, so a difference between what the docs describe and what Trello sends is caught where the response arrives.
🌳 Tree-shakable. Subpath exports per namespace (trello.js/boards, trello.js/cards, …), plus trello.js/models and trello.js/parameters. You pay for what you import.
📦 ESM-only. Node.js 22 and newer, browser-ready through any bundler.
🧪 Full API coverage. 17 namespaces and 250+ methods, generated from the official Trello swagger.
⚡ Built-in retry. 429 responses retry on their own, with exponential backoff.
📐 One runtime dependency. Just zod.

Installation

Requires Node.js 22+ and an ESM project ("type": "module" or a bundler).

pnpm add trello.js
# or
npm install trello.js
# or
yarn add trello.js

Quick start

Get your API key and token from Trello.
Create a client and make your first call:

import { createTrelloClient } from 'trello.js';

const trello = createTrelloClient({
  apiKey: process.env.TRELLO_KEY!,
  apiToken: process.env.TRELLO_TOKEN!,
});

const board = await trello.boards.createBoard({
  name: 'My first board',
  desc: 'From trello.js with love',
});

console.log(board.url);

Recipes

Boards

const board = await trello.boards.getBoard({ id: boardId });
const lists = await trello.boards.getBoardLists({ id: boardId });

await trello.boards.updateBoard({ id: boardId, closed: true });

Cards

const card = await trello.cards.createCard({
  idList: listId,
  name: 'Write release notes',
  pos: 'top',
});

await trello.cards.updateCard({ id: card.id, idList: targetListId });
await trello.cards.createCardComment({ id: card.id, text: 'Done.' });

Search

const result = await trello.search.search({
  query: 'release',
  modelTypes: 'cards,boards',
  cards_limit: 20,
});

result.cards?.forEach((c) => console.log(c.name));

Webhooks

const webhook = await trello.webhooks.createWebhook({
  idModel: boardId,
  callbackURL: 'https://my-app.example.com/trello/hook',
  description: 'Activity stream',
});

Your callbackURL has to answer a HEAD request with 200. Trello checks it at creation time.

Tree-shakable imports

To keep the bundle as small as possible, import the namespace functions directly:

import { createClient } from 'trello.js/core';
import { getBoard } from 'trello.js/boards';
import { createCard } from 'trello.js/cards';

const client = createClient({ apiKey, apiToken });

const board = await getBoard(client, { id });
const card = await createCard(client, { idList: board.idLists?.[0], name: 'Hi' });

Bundlers strip out unused namespaces. The 15+ namespaces you don't import never end up in your output.

TypeScript & schemas

Return types come with the methods:

const board = await trello.boards.getBoard({ id });
//    ^? Board

Every model also has a runtime Zod schema. Import it from the root or from the dedicated subpath:

import { BoardSchema, type Board } from 'trello.js/models';

const board: Board = BoardSchema.parse(payload);

To bypass parsing entirely, pass skipParsing: true when creating the client. schema.parse() is then never called, so no response raises ZodError and the schema transforms are skipped as well: date fields stay strings instead of becoming Date objects. That trades runtime type safety for speed and for resilience against schema drift, so leave it false (the default) unless you have a reason.

const trello = createTrelloClient({ apiKey, apiToken, skipParsing: true });

Error handling

Non-2xx responses throw Error('Request failed: <status> <statusText> - <body>'), and schema mismatches throw ZodError. Rate-limited 429s retry automatically, waiting 2 s, then 4 s, then 8 s.

try {
  await trello.boards.getBoard({ id: 'bad' });
} catch (err) {
  if (err instanceof Error && err.message.includes('404')) {
    // handle not-found
  }
}

See the error handling guide for details.

Documentation

📖 Full documentation: guides, recipes, migration.
📚 API reference: every method, generated from source.
🇷🇺 Русская версия.

Compatibility

Node.js ≥ 22 (ESM-only)
TypeScript ≥ 6.0 recommended
Modern bundlers: Vite, webpack 5+, Rollup, esbuild