tsconfig.json
Тема дорожной карты · Node.js
tsconfig.json — это файл конфигурации компилятора TypeScript, управляющий тем, как исходный TypeScript-код компилируется в JavaScript для среды выполнения Node.js; его настройки оказывают значительное влияние на типовую безопасность, формат модулей и совместимость вывода сборки. Для серверной разработки на Node.js наиболее важные настройки tsconfig.json включают: "target": "ES2022" для включения современных JavaScript-функций, нативно поддерживаемых Node.js 18+, "module": "CommonJS" или "module": "NodeNext" для соответствия системе модулей, "outDir": "./dist" для директории скомпилированного вывода, "strict": true для включения полного набора проверок типов TypeScript и "sourceMap": true для отлаживаемых трассировок стека в продакшне. Массив "lib" задаёт, какие встроенные JavaScript API доступны TypeScript, и для Node.js-проектов следует исключать типы DOM; npm-пакет @types/node предоставляет типизацию для всех встроенных модулей Node.js и должен быть указан в devDependencies. Псевдонимы путей, настроенные через "paths" в tsconfig.json, являются исключительно TypeScript-функцией времени компиляции и должны разрешаться во время выполнения с помощью tsconfig-paths или компилироваться в относительные импорты инструментом сборки. Массивы "include" и "exclude" управляют тем, какие файлы входят в компиляцию TypeScript, а исключение node_modules, dist и директорий с тестовыми фикстурами ускоряет время компиляции в крупных кодовых базах Node.js.
Как это работает
tsconfig.json добавляет статическую типизацию к 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 — это против смысла.
Типичные ошибки
Ловушки tsconfig.json: уход в any когда типы мешают (рефакторьте, не кастуйте); tsc для компиляции в CI (медленно — отдавайте swc/esbuild, tsc — только проверка типов); расходящиеся runtime + type-check пайплайны пропускают ошибки; забыли обновить @types/node вместе с major Node; гонка за strict: false "чтобы быстрее" (баги вернутся позже).