English · Русский
- 🔒 Fully typed — every endpoint, parameter, and response. No
any, no guessing. - ✅ Runtime validation powered by Zod 4 — drift between docs and reality is caught at the boundary.
- 🌳 Tree-shakable — subpath exports per namespace (
trello.js/boards,trello.js/cards, …) plustrello.js/modelsandtrello.js/parameters. Pay only for what you import. - 📦 ESM-only, modern Node.js (≥22), browser-ready via any bundler.
- 🧪 Full API coverage — 17 namespaces, 250+ methods, auto-generated from the official Trello swagger.
- ⚡ Built-in retry for 429 responses with exponential backoff.
- 📐 One runtime dependency —
zod.
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- 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);That's it.
const board = await trello.boards.getBoard({ id: boardId });
const lists = await trello.boards.getBoardLists({ id: boardId });
await trello.boards.updateBoard({ id: boardId, closed: true });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.' });const result = await trello.search.search({
query: 'release',
modelTypes: 'cards,boards',
cards_limit: 20,
});
result.cards?.forEach((c) => console.log(c.name));const webhook = await trello.webhooks.createWebhook({
idModel: boardId,
callbackURL: 'https://my-app.example.com/trello/hook',
description: 'Activity stream',
});Your
callbackURLmust respond200to aHEADrequest — Trello checks it at creation time.
For the smallest possible bundle, 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.
Types flow from the methods automatically:
const board = await trello.boards.getBoard({ id });
// ^? BoardEvery model also has a runtime Zod schema. Import from the root or the dedicated subpath:
import { BoardSchema, type Board } from 'trello.js/models';
const board: Board = BoardSchema.parse(payload);Need to bypass parsing entirely? Pass skipParsing: true when creating the client. schema.parse() is then skipped — no ZodError, no validation, and no schema transforms (date fields stay strings rather than Date objects). This trades runtime type-safety for speed and resilience against schema drift; leave it false (the default) unless you have a reason.
const trello = createTrelloClient({ apiKey, apiToken, skipParsing: true });Non-2xx responses throw Error('Request failed: <status> <statusText> - <body>'). Schema mismatches throw ZodError. Rate-limit 429s retry automatically (2 s, 4 s, 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.
📖 Full documentation — guides, recipes, migration
📚 API reference — every method, generated from source
🇷🇺 Русская версия
- Node.js ≥ 22 (ESM-only)
- TypeScript ≥ 6.0 recommended
- Modern bundlers: Vite, webpack 5+, Rollup, esbuild
See the v1 → v2 migration guide. Headline changes: new TrelloClient → createTrelloClient, key/token → apiKey/apiToken, ESM-only, Node 22+.
See CONTRIBUTING.md. Most of src/ is auto-generated from the Trello swagger — please don't hand-edit src/api/, src/models/, or src/parameters/.
MIT © Vladislav Tupikin