TypeScript Конфигурация

Файл tsconfig.json является сердцем каждого проекта на TypeScript.

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

Хорошо сконфигурированный файл tsconfig.json обеспечивает гладкий опыт разработки и надежные сборки.

Основные концепции и пояснения

compilerOptions: контролирует, как TypeScript компилирует ваш код (например, целевая спецификация, модульная система, степень строгости):
- target: версия ECMAScript для вывода.
  Значения: ES3 (по умолчанию), ES5, ES6/ES2015, ..., ESNext.
- module: система модулей (синтаксис import/export).
  Значения: CommonJS, AMD, UMD, System, ES2015, ES2020, ESNext, NodeNext.
- outDir: папка для скомпилированных .js‑файлов.
- rootDir: корневая папка с исходным кодом (если отличается от outDir).
- declaration: генерировать .d.ts (типовые декларации).
  Значение: true/false.
- sourceMap: создавать .map‑файлы для отладки.
  Значение: true/false.
- removeComments: удалять комментарии из вывода.
  Значение: true/false.
- outFile: объединить все файлы в один .js.
  Пример: "outFile": "bundle.js".
- strict: включить все строгие проверки.
  Значение: true/false.
  Включает: noImplicitAny, strictNullChecks, strictFunctionTypes и др.
- noImplicitAny: запрещать неявный any.
  Значение: true/false.
- strictNullChecks: проверять null/undefined.
  Значение: true/false.
- noUncheckedIndexedAccess: требовать проверку существования свойства при индексировании.
  Значение: true/false.
- alwaysStrict: добавлять "use strict" во все файлы.
  Значение: true/false.
- moduleResolution: алгоритм поиска модулей.
  Значения: Node, NodeNext, Bundler.
- baseUrl: базовая папка для абсолютных импортов.
- paths: алиасы для путей.
  Пример:
```
"paths": {
  "@app/*": ["src/app/*"],
  "@utils/*": ["src/utils/*"]
}
```
- resolveJsonModule: разрешать импорт .json.
  Значение: true/false.
- allowJs: разрешать .js в проекте.
  Значение: true/false.
- skipLibCheck: пропускать проверку типов в .d.ts.
  Значение: true/false.
- incremental: включать инкрементальную компиляцию.
  Значение: true/false.
- composite: для монорепозиториев (создаёт .tsbuildinfo).
  Значение: true/false.
- declarationMap: карты для .d.ts (отладка типов).
  Значение: true/false.
- lib: встроенные типы JS/DOM.
  Значения: es5, es2015, dom, dom.iterable, scripthost и др.
  Пример: "lib": ["es2022", "dom"].
- jsx: обработка JSX.
  Значения: preserve, react, react-native, react-jsx, react-jsxdev.
- esModuleInterop: совместимость CommonJS/ES‑модулей.
  Значение: true/false.
- isolatedModules: безопасность при обработке файлов как изолированных модулей.
  Значение: true/false.
- noEmit: не выводить файлы (только проверка типов).
  Значение: true/false.
- pretty: форматированные сообщения об ошибках.
  Значение: true/false.
- traceResolution: логировать процесс разрешения модулей.
  Значение: true/false.
- listFiles: выводить список обрабатываемых файлов.
  Значение: true/false.
- diagnostics: детализированная статистика компиляции.
  Значение: true/false.
include: файлы или каталоги, которые следует включить в компиляцию.
exclude: файлы или каталоги, которые следует исключить из компиляции.
files: явный список файлов для включения (редко используется, если указан параметр include).
extends: наследует опции из другого конфигурационного файла.
references: позволяет использовать проектные ссылки для монорепозиториев или многопакетных установок.

Пошаговые примеры

Минимальный tsconfig.json


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

Продвинутый tsconfig.json


{
  "compilerOptions": {
    "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 для генерации файлов определений типов.
Приложение: используйте опции strict и esModuleInterop для наилучшей совместимости.

Распространённые проблемы

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

Лучшие практики

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