Как настраивается tsconfig.json? Какие параметры компилятора наиболее важны?

Ключевые параметры tsconfig.json

tsconfig.json управляет поведением компилятора TypeScript. Правильная настройка критична для корректности типов, производительности сборки и совместимости с рантаймом.

Базовая конфигурация (современный проект)

{
  "compilerOptions": {
    // Целевой ES-стандарт вывода
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],

    // Модульная система
    "module": "NodeNext",
    "moduleResolution": "NodeNext",

    // Строгость
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Вывод
    "outDir": "./dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,

    // Производительность
    "incremental": true,
    "skipLibCheck": true,

    // Совместимость
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Разбор важных параметров

strict

Включает группу флагов: strictNullChecks, strictFunctionTypes, strictPropertyInitialization, noImplicitAny, noImplicitThis, alwaysStrict. Без strict TypeScript прощает большинство ошибок.

target vs lib

target — во что компилируется код (ES5 добавит polyfills для стрелочных функций). lib — какие типы DOM/ES API доступны для type-checking. Можно иметь target: ES5 + lib: ["ES2022"] для сред с polyfill-ами.

module и moduleResolution

// Node.js приложение (ESM)
{ "module": "NodeNext", "moduleResolution": "NodeNext" }

// Приложение с Vite/webpack
{ "module": "ESNext", "moduleResolution": "Bundler" }

// Старый CJS Node.js
{ "module": "CommonJS", "moduleResolution": "Node" }

isolatedModules

Требует, чтобы каждый файл был self-contained — совместимость с esbuild/SWC, которые не делают type-checking, а только транспилируют файл за файлом:

// Ошибка при isolatedModules: true
export { MyType }; // нужно export type { MyType }

// Правильно
export type { MyType };

noUncheckedIndexedAccess

const arr: string[] = ['a', 'b'];
const item = arr[0]; // без флага: string; с флагом: string | undefined
if (item !== undefined) {
  console.log(item.toUpperCase()); // теперь безопасно
}

paths и baseUrl

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

composite для монорепо

// packages/ui/tsconfig.json
{ "compilerOptions": { "composite": true, "declaration": true } }

// apps/web/tsconfig.json
{ "references": [{ "path": "../../packages/ui" }] }

Позволяет tsc -b (build mode) пересобирать только изменившиеся пакеты.

Подводные камни

• strict: true на существующей JS-кодовой базе сразу даёт сотни ошибок — используйте // @ts-nocheck в legacy файлах и мигрируйте постепенно.
• esModuleInterop: false + CJS пакеты: придётся писать import * as fs from 'fs' вместо import fs from 'fs'.
• skipLibCheck: true скрывает конфликты типов в node_modules — может маскировать реальные баги при несовместимых версиях пакетов.
• target: ES5 не добавляет polyfills автоматически — только синтаксис, не API (Array.prototype.flat и т.д.).
• При moduleResolution: NodeNext обязательны .js расширения в import путях — это ломает привычный workflow.
• Несколько tsconfig файлов (base, app, test) должны явно расширять друг друга через extends, иначе настройки не наследуются.
• exactOptionalPropertyTypes ломает паттерн { ...obj, key: undefined } для удаления полей — нужно явно удалять через delete.
• IDE использует свой tsconfig, а bundler — свой; расхождение настроек приводит к «работает в IDE, ломается в сборке».

• Смешивать «tsconfig.json» с похожим механизмом без критерия выбора.
• Игнорировать риск: неверно оценить границы применения темы «tsconfig.json» и получить хрупкое решение.
• Показывать только синтаксис и не объяснять поведение в runtime или сборке.

• Объясняет настройка компилятора, strict mode, module target и JSX.
• Показывает на примере, как работает: tsconfig задает границу проекта и правила проверки; сильный кандидат объясняет strict, target, module, moduleResolution, jsx, lib, paths, noEmit и инкрементальную сборку.
• Называет production-нюанс и граничный случай для темы «tsconfig.json».