README.ru.md

August 20, 2026 · View on GitHub

trello.js logo

trello.js

npm version npm downloads bundle size CI license

Типобезопасный клиент Trello REST API для Node.js и браузеров.

English · Русский

Почему trello.js

  • 🔒 Полная типизация. Тип есть у каждого эндпоинта, параметра и ответа, any не остаётся нигде.
  • ✅ Runtime-валидация. Ответы проверяются через Zod 4: расхождение между документацией и тем, что реально присылает Trello, ловится там, где приходит ответ.
  • 🌳 Tree-shakable. Subpath-экспорты на каждый namespace (trello.js/boards, trello.js/cards, …), плюс trello.js/models и trello.js/parameters. Вы платите только за то, что импортируете.
  • 📦 Только ESM. Node.js 22 и новее, работает в браузере через любой сборщик.
  • 🧪 Полное покрытие API. 17 namespace и 250+ методов, генерируется из официального swagger Trello.
  • ⚡ Встроенный retry. 429-ответы ретраятся сами, с экспоненциальным backoff.
  • 📐 Одна runtime-зависимость. Только zod.

Установка

Требуется Node.js 22+ и ESM-проект ("type": "module" или сборщик).

pnpm add trello.js
# или
npm install trello.js
# или
yarn add trello.js

Быстрый старт

  1. Получите API key и token от Trello.
  2. Создайте клиент и сделайте первый запрос:
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: 'Моя первая доска',
  desc: 'From trello.js with love',
});

console.log(board.url);

Рецепты

Доски

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: 'Написать release notes',
  pos: 'top',
});

await trello.cards.updateCard({ id: card.id, idList: targetListId });
await trello.cards.createCardComment({ id: card.id, text: 'Готово.' });

Поиск

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: 'Стрим активности',
});

callbackURL должен отвечать 200 на HEAD-запрос. Trello проверяет это в момент создания.

Tree-shaking-импорты

Чтобы бандл был минимальным, импортируйте функции namespace'ов напрямую:

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

Сборщики выкидывают неиспользуемые namespace. Те 15+ namespace'ов, которые вы не импортируете, в бандл не попадут.

TypeScript и схемы

Типы возвращаемых значений приходят вместе с методами:

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

У каждой модели есть runtime Zod-схема. Импортировать её можно из корня или из отдельного subpath:

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

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

Чтобы полностью отключить парсинг, передайте skipParsing: true при создании клиента. Тогда schema.parse() не вызывается: ZodError не бросается, трансформации схемы тоже не применяются, поэтому даты остаются строками, а не становятся объектами Date. Это размен рантайм-типобезопасности на скорость и устойчивость к дрейфу схем, так что оставляйте false (значение по умолчанию), если нет причин менять.

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

Обработка ошибок

Non-2xx ответы бросают Error('Request failed: <status> <statusText> - <body>'), несовпадения схемы — ZodError. Ответы 429 от рейт-лимита ретраятся автоматически: сначала пауза 2 с, потом 4 с, потом 8 с.

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

Подробности — в гайде по обработке ошибок.

Документация

Совместимость

  • Node.js ≥ 22 (только ESM)
  • TypeScript ≥ 6.0 рекомендуется
  • Современные сборщики: Vite, webpack 5+, Rollup, esbuild

Мигрируете с v1?

См. гайд миграции v1 → v2. Главные изменения: new TrelloClient заменён на createTrelloClient, key/token — на apiKey/apiToken, пакет стал только-ESM и требует Node 22+.

Contributing

См. CONTRIBUTING.md. Большая часть src/ генерируется из swagger Trello, поэтому, пожалуйста, не редактируйте вручную src/api/, src/models/ и src/parameters/.

Лицензия

MIT © Vladislav Tupikin