tsconfig.json: основные опции

tsconfig.json — файл конфигурации TypeScript-компилятора, управляющий строгостью проверок, целевой версией JS, разрешением модулей, структурой вывода и включаемыми файлами.

Зачем нужно

Правильная конфигурация tsconfig определяет: какие файлы компилируются, насколько строгие проверки, в какой JS-версию компилировать и как разрешаются модули. Неверные настройки могут скрыть реальные ошибки или создать несовместимость с runtime-окружением.

Где используется

  • Каждый TypeScript-проект имеет tsconfig.json в корне
  • Монорепозитории используют базовый tsconfig + extends в каждом пакете
  • Разные tsconfig для тестов, library build, app build

Основной контент

Структура файла

{
  "compilerOptions": { /* настройки компилятора */ },
  "include": ["src/**/*"],     // какие файлы включать
  "exclude": ["node_modules", "dist"],
  "extends": "./tsconfig.base.json()"  // наследование
}

Ключевые группы опций

Целевое окружение

{
  "target": "ES2022",
  // ES3, ES5, ES2015..ES2023, ESNext
  // Определяет в какой JS-синтаксис транспилировать

  "lib": ["ES2022", "DOM", "DOM.Iterable"],
  // Встроенные API: DOM для браузера, ES2022 для Promise.allSettled и т.д.
  // Без DOM — нет типов для document, window, fetch

  "module": "NodeNext",
  // CommonJS — Node.js legacy
  // NodeNext — современный Node.js с ESM
  // ESNext — для bundler (Vite, webpack)
  // bundler — TS 5.0+, для bundler окружения

  "moduleResolution": "NodeNext"
  // Как разрешать импорты: node, node16, nodenext, bundler
}

Строгость

{
  "strict": true,
  // Включает все strict-флаги:
  "strictNullChecks": true,           // null/undefined не совместимы с другими типами
  "noImplicitAny": true,              // запрет неявного any
  "strictFunctionTypes": true,        // строгая проверка функциональных типов
  "strictPropertyInitialization": true, // поля класса должны быть инициализированы

  // Дополнительные (не входят в strict):
  "noUncheckedIndexedAccess": true,   // arr[0]: T | undefined
  "exactOptionalPropertyTypes": true, // различает отсутствие и undefined
  "noImplicitReturns": true,          // все ветки функции должны возвращать значение
  "noFallthroughCasesInSwitch": true  // запрет fall-through в switch
}

Вывод файлов

{
  "outDir": "./dist",          // куда выводить .js файлы
  "rootDir": "./src",          // корень исходников
  "declaration": true,         // генерировать .d.ts файлы
  "declarationDir": "./types", // куда выводить .d.ts
  "sourceMap": true,           // генерировать .js.map для отладки
  "noEmit": true               // только проверка типов, без файлов (для bundler)
}

Совместимость и импорты

{
  "esModuleInterop": true,              // import fs from 'fs' вместо * as fs
  "allowSyntheticDefaultImports": true, // разрешить default import из CJS модулей
  "skipLibCheck": true,                 // не проверять .d.ts в node_modules
  "forceConsistentCasingInFileNames": true, // чувствительность к регистру имён файлов
  "paths": {
    "@/*": ["./src/*"]                  // алиасы путей
  },
  "baseUrl": "."
}

Конфигурация для разных сред

// Node.js (современный)
{
  "compilerOptions": {
    "target": "ES2022", "module": "NodeNext",
    "moduleResolution": "NodeNext", "strict": true,
    "outDir": "./dist", "rootDir": "./src"
  }
}

// Браузер + bundler (Vite)
{
  "compilerOptions": {
    "target": "ES2020", "module": "ESNext",
    "moduleResolution": "bundler", "jsx": "react-jsx",
    "strict": true, "noEmit": true
  }
}

// Библиотека (npm пакет)
{
  "compilerOptions": {
    "target": "ES2017", "module": "CommonJS",
    "declaration": true, "declarationDir": "./types",
    "strict": true, "outDir": "./dist"
  }
}

Частые ошибки

  • Не включать strict: true — без него TypeScript значительно мягче.
  • Неверный module + moduleResolution — module: NodeNext требует moduleResolution: NodeNext; несоответствие вызовет ошибки импортов.
  • Не указывать rootDir — компилятор будет искать общий корень всех файлов, что может сломать структуру вывода.
  • skipLibCheck: false в строгих проектах — проверка node_modules замедляет компиляцию и часто даёт ложные ошибки; лучше true.

Связанные темы

Ресурсы