README.md

May 31, 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. 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, …) plus trello.js/models and trello.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.

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

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 must respond 200 to a HEAD request — Trello checks it at creation time.

Tree-shakable imports

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.

TypeScript & schemas

Types flow from the methods automatically:

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

Every 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 });

Error handling

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.

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