Сборка TypeScript
Тема дорожной карты · Node.js
Сборка TypeScript-проекта для Node.js включает компиляцию исходных файлов .ts в JavaScript, который может выполнять среда выполнения Node.js, с использованием либо компилятора TypeScript (tsc), либо более быстрых альтернатив вроде esbuild, swc или tsx. Стандартный процесс сборки TypeScript выполняет tsc --project tsconfig.json, который читает параметры компилятора, проверяет типы проекта и выводит скомпилированный JavaScript в директорию вывода, указанную в outDir — обычно dist/, — сохраняя структуру исходной директории по умолчанию. Для продакшн-развёртываний Node.js шаг сборки выполняется внутри Docker-сборки с несколькими этапами, чтобы в финальный образ контейнера попадали только скомпилированная директория dist/ и продакшн-модули node_modules, исключая TypeScript-исходники, devDependencies и сам компилятор TypeScript. Более быстрые инструменты сборки, такие как esbuild и swc, транспилируют TypeScript в JavaScript без проверки типов, что значительно сокращает время сборки в CI/CD, но требует отдельного шага tsc --noEmit для обнаружения ошибок типов. Source maps, генерируемые с настройкой "sourceMap": true в tsconfig.json, необходимы для информативных трассировок стека в продакшн-мониторинге ошибок Node.js, сопоставляя номера строк скомпилированного JavaScript с исходными строками TypeScript.
Как это работает
Сборка TypeScript добавляет статическую типизацию к JavaScript через TypeScript-компилятор (tsc) или runtime-трансформеры (tsx, ts-node, swc, esbuild). tsconfig.json контролирует строгость; strict: true — современный дефолт, ловит много багов на сборке. Type-декларации для npm-пакетов — из пакета или DefinitelyTyped (@types/*). Современные проекты компилируют через SWC/esbuild для скорости, типы проверяют отдельно tsc --noEmit в CI.
Когда применять
TypeScript — в каждый новый Node-проект: кривая обучения маленькая, выигрыш большой (ловит опечатки, безопасные рефакторы, IDE-автокомплит). Даже однофайловые скрипты выигрывают. Тонкий runtime-трансформер (tsx) в dev для мгновенного фидбека; реальная проверка типов (tsc --noEmit) — в CI. Избегайте any и @ts-ignore — это против смысла.
Типичные ошибки
Ловушки Сборка TypeScript: уход в any когда типы мешают (рефакторьте, не кастуйте); tsc для компиляции в CI (медленно — отдавайте swc/esbuild, tsc — только проверка типов); расходящиеся runtime + type-check пайплайны пропускают ошибки; забыли обновить @types/node вместе с major Node; гонка за strict: false "чтобы быстрее" (баги вернутся позже).