Интеграция Temporal API, TypeDoc и Prettier для автоматизации docs в TS: гайд 2026

[kirilljsx]

В TypeScript-проектах с Temporal API часто приходится документировать workflows, activities и датовые структуры. Ручная работа с docs отнимает часы, а код меняется - и всё устаревает. Этот гайд покажет, как связать Temporal, TypeDoc и Prettier в пайплайн для автогенерации чистой документации. Получится статический сайт с актуальными примерами, форматированный идеально.

Такой подход экономит время: один npm-скрипт - и docs готовы к деплою. Подходит для пет-проектов или продакшена с worker’ами. Разберём установку, конфиг и автоматизацию шаг за шагом.

Что такое Temporal API и зачем docs автоматизировать

Temporal - это платформа для оркестрации долгоживущих процессов в TS/Node.js. Workflows и activities там пишутся с датами, таймерами, ретраями - всё асинхронно и надёжно. Но без docs новички тонут в коде: как понять, какие даты передавать в activity или как сериализовать Date в workflow?

TypeDoc парсит JSDoc-комменты и генерит HTML-сайт с типами, примерами. Prettier держит код и конфиги в одном стиле - никаких споров о кавычках или отступах. Вместе они решают проблему: код меняется - docs обновляются автоматически. Представь worker с background-check: даты проверок, статусы - всё документируется на лету. Логично перейти к настройке: сначала ставим пакеты, потом конфиги.

• Установи Temporal TS SDK: npm i @temporalio/client @temporalio/worker
• Добавь TypeDoc глобально или локально: npm i -D typedoc
• Prettier для форматирования: npm i -D prettier
• В tsconfig.json включи strict режим для точных типов дат.

Инструмент	Роль в пайплайне	Пример флаг
Temporal	Workflows/Activities с датами	scheduleToCloseTimeout: '1d'
TypeDoc	Генерация HTML из JSDoc	--excludePrivate
Prettier	Форматирование .md и .json	semi: false

Настройка TypeDoc под Temporal workflows

TypeDoc сканнит TS-файлы, pulls JSDoc и строит дерево классов. Для Temporal фокусируйся на interfaces для дат: interface CheckDate { start: Date; end: Date; }. В комментах добавляй @link на Temporal типы - документация станет интерактивной.

Пример workflow с датами: worker регистрирует activities, TypeDoc описывает каждый метод. Prettier форматирует JSDoc - отступы ровные, код в блоках. Без этого docs - каша. А с пайплайном: измени Date в коде - перегенерируй и готово. Теперь к шагам конфигурации.

1. Создай typedoc.json:

   {
     "entryPoints": ["src/workflows.ts"],
     "out": "docs",
     "readme": "README.md",
     "excludePrivate": true,
     "excludeExternals": true
   }
   

2. В JSDoc для activity: /** @param dates: Date[] Проверяет сроки workflow */
3. Нюанс: Temporal даты сериализуются в ISO - укажи в docs @returns string (ISO Date).
4. Запуск: npx typedoc - получишь сайт в /docs.

Сравнение до/после:

Без автоматизации	С TypeDoc + Prettier
Ручные .md файлы	Авто-HTML с типами
Устаревшие даты	Связь с кодом
Разный стиль	Prettier-идеал

Интеграция Prettier в пайплайн документации

Prettier - must-have для TS-проектов с Temporal: форматирует не только код, но и .rc файлы, JSDoc. Без него конфиги TypeDoc - с разными отступами, а README с двойными кавычками. Добавь скрипт в package.json - и всё на автопилоте.

В Temporal-приложениях activities часто имеют Date-параметры: Prettier сделает их читаемыми. Пример: в workflows.ts форматирует new Date() в аккуратный блок. Связь с TypeDoc: сначала prettier src/, потом typedoc. Это цепочка: чистый код -> чистые docs. Разберём .prettierrc и npm-скрипты.

• .prettierrc (в формате JS для комментариев):

  module.exports = {
    semi: false,
    singleQuote: true,
    trailingComma: 'es5',
    printWidth: 80
  };
  

• Скрипт в package.json: "docs": "prettier . && typedoc"
• Важно: Исключи node_modules: --ignore-path .prettierignore.
• Интегрируй с VSCode: extension auto-format on save.

Для Temporal добавь в .prettierignore: dist/, но держи src/ под форматированием.

Автоматизация всего пайплайна с датами в фокусе

Temporal workflows полны дат: retry dates, timeouts. Автоматизируй docs через GitHub Actions или локальный скрипт. TypeDoc увидит изменения в Date-типах, Prettier - отформатирует. Результат: деплоишь worker - docs обновлены.

Пример worker кода с docs:

import { Worker } from '@temporalio/worker';

/** 
 * Workflow с датами проверок.
 * @param startDate - начало периода
 */
export async function checkWorkflow(startDate: Date) { ... }

Prettier сделает отступы, TypeDoc - с��раницу. Добавь husky для pre-commit: git commit -> format -> typedoc preview.

1. Husky + lint-staged: npm i -D husky lint-staged
2. .husky/pre-commit: npx lint-staged
3. lint-staged: { '*.ts': 'prettier --write', '*.json': 'prettier --write' }
4. CI-скрипт: npm run docs && deploy-to-gh-pages.
5. Фича для 2026: Typedoc plugin для Temporal - auto-link workflows.

Шаг пайплайна	Команда	Вывод
Format	npm run format	Чистый код
Docs gen	npx typedoc	HTML сайт
Deploy	gh-pages -d docs	Онлайн docs

Пайплайн готов - даты документированы на века

Temporal + TypeDoc + Prettier дают docs, которые живут с кодом: измени Date в activity - сайт обновится. Осталось доработать: custom themes для TypeDoc под бренд, или интеграция с Temporal UI для live-примеров.

В 2026 такие пайплайны - стандарт для TS-команд. Подумай о тестах: snapshot docs после каждого билда. Или ML-промпт для auto-JSDoc - но это уже следующий уровень.