Настройка tsconfig.json в TypeScript

В этой главе объясняется файл tsconfig.json: для чего он нужен, какие настройки встречаются чаще всего и как избежать распространённых ошибок.

Файл tsconfig.json — это сердце любого проекта на TypeScript.

Он сообщает компилятору TypeScript, как обрабатывать ваш код, какие файлы входят в проект и какие возможности включить или выключить.

Хорошо настроенный tsconfig.json даёт удобную разработку и надёжную сборку.

Самые важные поля верхнего уровня:

• compilerOptions: управляет тем, как TypeScript компилирует ваш код (например, целевая версия, модульная система и строгость).
• include: файлы или папки, которые нужно включить в компиляцию.
• exclude: файлы или папки, которые нужно исключить.
• files: явный список включаемых файлов (редко используется вместе с include).
• extends: наследовать настройки из другого файла конфигурации.
• references: включает ссылки на проекты для монорепозиториев или сборок из нескольких пакетов.

Минимальному tsconfig.json нужны только целевая версия, модульная система и список включаемых файлов:

• "compilerOptions": { "target": "es6", "module": "commonjs" }
• "include": ["src/**/*"]

Более полная конфигурация для приложения добавляет строгую проверку, псевдонимы путей и папку для результата сборки:

• "target": "es2020"
• "module": "esnext"
• "strict": true
• "baseUrl": "."
• "paths": { "@app/*": ["src/app/*"] }
• "outDir": "dist"
• "esModuleInterop": true
• "include": ["src"]
• "exclude": ["node_modules", "dist"]

Чтобы создать стартовый tsconfig.json с комментариями к каждой настройке, выполните tsc --init.

• Монорепозиторий: используйте references и extends, чтобы делить общие настройки между пакетами.
• Библиотека: задайте declaration и outDir, чтобы файлы с определениями типов создавались рядом с результатом на JavaScript.
• Приложение: используйте strict и esModuleInterop для наилучшей совместимости.

• Неверный include или exclude может убрать файлы из сборки или, наоборот, добавить те, которых вы не ожидали.
• Пути не разрешаются? Проверьте настройки baseUrl и paths.
• Появились новые ошибки типов после включения strict? Это нормально. Пройдитесь по указанному коду и сделайте его безопасным по типам.

• Всегда включайте strict — так код безопаснее.
• Используйте extends, чтобы не повторять одну и ту же конфигурацию в монорепозиториях или в нескольких проектах.
• Не добавляйте папки с результатами сборки (например, dist) в систему контроля версий.