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

Что делает tsconfig.json:

• Определяет, какие файлы компилировать (и какие игнорировать)
• Задаёт целевую версию JavaScript, в которую транспилируется код
• Управляет уровнем строгости проверки типов
• Настраивает систему модулей
• Указывает, куда сохранять скомпилированные файлы
• Определяет, включать ли генерацию declaration-файлов
• Управляет генерацией source maps
• Задаёт доступные встроенные типы (lib)
• Влияет на поведение IDE (автодополнение, переходы, рефакторинг)

Почему tsconfig.json важен для команды:

В командной разработке каждый разработчик должен использовать одни и те же настройки компилятора. Если один разработчик компилирует код в ES5, а другой — в ES2020, результат может быть непредсказуемым. tsconfig.json хранится в репозитории и версионируется через Git, поэтому все участники команды работают с одинаковыми настройками.

tsc --init

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

// tsconfig.json — минимальная конфигурация
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "outDir": "./dist"
  }
}

Важно: Файл tsconfig.json должен находиться в корне проекта (или в корне packages/ для монорепозитория). Компилятор ищет его, поднимаясь по дереву директорий от файла, который компилируется, до корня файловой системы. Если tsconfig.json не найден в текущей директории, TypeScript попытается найти его в родительских каталогах.

# Простой проект
my-project/
├── tsconfig.json        ← в корне проекта
├── src/
│   ├── index.ts
│   └── utils.ts
└── package.json

# Монорепозиторий (monorepo)
monorepo/
├── tsconfig.json        ← базовая конфигурация
├── packages/
│   ├── core/
│   │   ├── tsconfig.json   ← наследует от корневого
│   │   └── src/
│   └── utils/
│       ├── tsconfig.json   ← наследует от корневого
│       └── src/

{
  "compilerOptions": {
    // ES5 — поддержка старых браузеров (IE11)
    // "target": "ES5",

    // ES2015 (ES6) — стрелочные функции, let/const, классы
    // "target": "ES2015",

    // ES2017 — async/await, Object.entries, Object.values
    // "target": "ES2017",

    // ES2020 — optional chaining (?.), nullish coalescing (??)
    // "target": "ES2020",

    // ES2022 — top-level await, class fields, at() method
    // "target": "ES2022",

    // ESNext — последняя доступная версия (всегда актуальная)
    // "target": "ESNext"

    // Рекомендованное значение для современных проектов:
    "target": "ES2020"
  }
}

Совет: Если вы не уверены, какой target выбрать, начните с "ES2020". Это покрывает большинство современных браузеров и Node.js 14+. Если нужна поддержка более старых окружений —откат до "ES2017" или "ES2015". Вы всегда можете изменить эту настройку позже.

{
  "compilerOptions": {
    // CommonJS — модули Node.js (require/module.exports)
    // "module": "commonjs",

    // ES2015 — нативные ES-модули (import/export)
    // "module": "ES2015",

    // ESNext — последняя версия ES-модулей
    // "module": "ESNext",

    // Node16/NodeNext — для Node.js с ESM-поддержкой
    // "module": "Node16",

    // Рекомендованное значение:
    "module": "ESNext"
  }
}

Важно: Выбор module должен соответствовать вашей среде выполнения. Браузеры поддерживают ES-модули через <script type="module">, но не все среды одинаково хорошо работают с динамическими импортами. Node.js до версии 14 экспериментально поддерживал ESM, а стабильная поддержка появилась в 14.x. Начиная с Node.js 16, ESM поддерживается полноценно.

{
  "compilerOptions": {
    // Включает ВСЕ перечисленные ниже опции:
    "strict": true,

    // Эквивалентно записи:
    // "noImplicitAny": true,
    // "strictNullChecks": true,
    // "strictFunctionTypes": true,
    // "strictBindCallApply": true,
    // "strictPropertyInitialization": true,
    // "noImplicitThis": true,
    // "useUnknownInCatchVariables": true,
    // "alwaysStrict": true
  }
}

// ❌ Ошибка: Parameter 'x' implicitly has an 'any' type
function double(x) {
  return x * 2;
}

// ✅ Правильно: явно указан тип
function double(x: number): number {
  return x * 2;
}

// ❌ Ошибка: Type 'null' is not assignable to type 'string'
const name: string = null;

// ✅ Правильно: явно указываем, что переменная может быть null
const name: string | null = null;

// ✅ Проверка перед использованием
function greet(name: string | null): string {
  if (name === null) {
    return 'Привет, незнакомец!';
  }
  return `Привет, ${name}!`;
}

function processAnimal(animal: { name: string; legs: number }) {
  console.log(animal.name, animal.legs);
}

// С strictFunctionTypes это будет ошибкой:
// const process: typeof processAnimal = (dog: { name: string }) => console.log(dog.name);

function add(a: number, b: number): number {
  return a + b;
}

// С strictBindCallApply типы сохраняются:
const add5 = add.bind(null, 5);
const result: number = add5(3); // ✅ result: number

class User {
  name: string;      // ❌ Ошибка: Property 'name' has no initializer
  age: number = 0;   // ✅ Инициализировано
  email?: string;     // ✅ Опциональное

  constructor(name: string) {
    this.name = name; // ✅ Инициализируется в конструкторе
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "outDir": "./dist"
  }
}

// Структура проекта:
my-project/
├── tsconfig.json
├── src/
│   ├── index.ts        ← исходный файл
│   └── utils/
│       └── math.ts     ← исходный файл
└── dist/               ← сюда компилируется
    ├── index.js
    └── utils/
        └── math.js

// tsconfig.json
{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

// Структура:
my-project/
├── tsconfig.json
├── src/
│   ├── index.ts
│   └── utils/
│       └── math.ts
├── tests/
│   └── math.test.ts     ← НЕ компилируется (вне rootDir)
└── dist/
    ├── index.js
    └── utils/
        └── math.js

Совет: Всегда указывайте rootDir, если исходные файлы находятся в поддиректории (например, src/). Без этого компилятор будет включать все файлы, включая конфигурационные, что приведёт к ненужной структуре в выходной директории.

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  // Какие файлы компилировать:
  "include": [
    "src/**/*.ts",        // Все .ts файлы в src и поддиректориях
    "src/**/*.tsx"        // Все .tsx файлы (React-компоненты)
  ],
  // Какие файлы исключить:
  "exclude": [
    "node_modules",       // Зависимости
    "dist",               // Выходная директория
    "tests",              // Тесты
    "**/*.test.ts",       // Файлы тестов
    "**/*.spec.ts",       // Файлы спецификаций
    "**/*.d.ts"           // Declaration файлы
  ]
}

{
  "compilerOptions": {
    // Только ES-типы (для Node.js):
    "lib": ["ES2020"],

    // ES + DOM (для браузеров):
    // "lib": ["ES2020", "DOM", "DOM.Iterable"],
  }
}

{
  "compilerOptions": {
    "noEmit": true,
    "strict": true
  }
}

// Теперь tsc проверяет типы, но не создаёт .js файлы:
// $ tsc --noEmit

Совет: Используйте noEmit в проектах с Webpack/Vite/esbuild. Эти инструменты берут на себя транспилирацию, а TypeScript отвечает только за проверку типов. Это ускоряет процесс разработки и избегает конфликтов.

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types"
  }
}

// Исходный файл: src/math.ts
export function add(a: number, b: number): number {
  return a + b;
}

// Сгенерированный файл: types/math.d.ts
export declare function add(a: number, b: number): number;

{
  "compilerOptions": {
    "sourceMap": true,        // Генерирует отдельные .map файлы
    // "inlineSourceMap": true  // Встраивает source map в .js файл
  }
}

// Результат:
dist/
├── index.js        ← скомпилированный код
├── index.js.map    ← source map (при sourceMap: true)
└── ...

Важно: Не публикуйте source map в продакшене, если не хотите, чтобы пользователи видели ваш исходный код. Source map — это по сути миниатюрная копия вашего кода. В продакшене source map обычно генерируются, но загружаются только при необходимости.

my-typescript-project/
├── tsconfig.json           # Конфигурация TypeScript
├── package.json            # Метаданные проекта и зависимости
├── .gitignore              # Игнорируемые файлы
├── src/                    # Исходный код
│   ├── index.ts            # Точка входа
│   ├── types/              # Пользовательские типы
│   │   ├── index.ts        # Экспорт всех типов
│   │   ├── user.ts         # Типы пользователя
│   │   └── api.ts          # Типы API
│   ├── utils/              # Утилиты
│   │   ├── index.ts
│   │   ├── validation.ts
│   │   └── formatting.ts
│   ├── services/           # Бизнес-логика
│   │   ├── index.ts
│   │   ├── authService.ts
│   │   └── userService.ts
│   └── config/             # Конфигурация приложения
│       ├── index.ts
│       └── constants.ts
├── dist/                   # Скомпилированный код (не коммитится)
│   ├── index.js
│   └── ...
└── node_modules/           # Зависимости (не коммитится)

// Подход 1: Типы рядом с кодом
src/
├── models/
│   ├── User.ts        # Содержит интерфейс User
│   └── Post.ts        # Содержит интерфейс Post
└── services/
    ├── authService.ts # Использует типы из models
    └── userService.ts # Использует типы из models

// Подход 2: Отдельная папка для типов
src/
├── types/
│   ├── index.ts       # Единая точка экспорта
│   ├── user.ts        # Интерфейс User
│   └── api.ts         # Типы API-ответов
├── models/
│   ├── User.ts
│   └── Post.ts
└── services/
    └── userService.ts # Импортирует из types/

// src/types/index.ts
export { User } from './user';
export { Post } from './post';
export { ApiResponse } from './api';

// src/utils/index.ts
export { validate } from './validation';
export { formatDate } from './formatting';
export { generateId } from './helpers';

// Использование в других файлах:
import { User, Post } from '../types';
import { validate, formatDate } from '../utils';

Совет: Barrel exports удобны для импорта, но могут вызвать проблемы с tree-shaking (удалением неиспользуемого кода) в некоторых сборщиках. Если производительность критична, импортируйте файлы напрямую, а barrel exports используйте только в корне пакета.

// tsconfig.json для библиотеки
{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "declarationDir": "./types",
    "outDir": "./dist"
  }
}

// Структура после компиляции:
my-library/
├── src/
│   ├── index.ts
│   └── utils.ts
├── dist/
│   ├── index.js
│   ├── index.d.ts         # Declaration файл
│   ├── index.d.ts.map     # Source map для declaration
│   ├── utils.js
│   └── utils.d.ts
└── package.json
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"

// tsconfig.json — Библиотека (npm-пакет)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",

    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,

    "declaration": true,
    "declarationMap": true,
    "declarationDir": "./types",

    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",

    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,

    "resolveJsonModule": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": [
    "node_modules",
    "dist",
    "types",
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/*.d.ts"
  ]
}

// package.json
{
  "name": "my-awesome-lib",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./types/index.d.ts",
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.js"
    }
  },
  "files": ["dist", "types"],
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "prepublishOnly": "npm run build"
  }
}

// tsconfig.json — Веб-приложение (React)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",

    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,

    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"],
      "@hooks/*": ["./src/hooks/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

// tsconfig.json — Node.js сервер
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "Node16",

    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,

    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,

    "resolveJsonModule": true,
    "isolatedModules": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

// tsconfig.base.json (в корне monorepo)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "sourceMap": true,
    "isolatedModules": true
  }
}

// packages/core/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"]
}

// packages/web/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": true,
    "jsx": "react-jsx",
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

{
  "compilerOptions": {
    "noUnusedLocals": true,       // Ошибка при неиспользуемых переменных
    "noUnusedParameters": true    // Ошибка при неиспользуемых параметрах
  }
}

// ❌ Ошибка: 'unused' is declared but never used
const unused = 42;

// ❌ Ошибка: 'x' is declared but its value is never read
function doSomething(x: number): number {
  return 1;
}

{
  "compilerOptions": {
    "noImplicitReturns": true
  }
}

// ❌ Ошибка: Not all code paths return a value
function getArea(shape: string, width: number, height: number): number {
  if (shape === 'rectangle') {
    return width * height;
  }
  // Нет return для других вариантов!
}

// ✅ Правильно:
function getArea(shape: string, width: number, height: number): number {
  if (shape === 'rectangle') {
    return width * height;
  }
  return 0; // дефолтное значение
}

{
  "compilerOptions": {
    "noFallthroughCasesInSwitch": true
  }
}

// ❌ Ошибка: Fallthrough case in switch
function getDayType(day: string): string {
  switch (day) {
    case 'monday':
      return 'weekday';
    case 'tuesday':
      // Oops, forgot break!
    case 'wednesday':
      return 'weekday';
    default:
      return 'unknown';
  }
}

{
  "compilerOptions": {
    "noUncheckedIndexedAccess": true
  }
}

const arr: number[] = [1, 2, 3];

// С noUncheckedIndexedAccess:
const item = arr[0]; // тип: number | undefined

// ❌ Ошибка: Object is possibly 'undefined'
console.log(item.toFixed(2));

// ✅ Правильно:
if (item !== undefined) {
  console.log(item.toFixed(2));
}

{
  "compilerOptions": {
    "exactOptionalPropertyTypes": true
  }
}

interface Config {
  name?: string;  // Может быть undefined?
  age?: number;
}

// С exactOptionalPropertyTypes:
const config1: Config = { name: "test" };           // ✅
const config2: Config = { name: undefined };         // ❌ Ошибка!
const config3: Config = {};                          // ✅

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"],
      "@hooks/*": ["./src/hooks/*"],
      "@services/*": ["./src/services/*"]
    }
  }
}

// Вместо:
import { Button } from '../../../components/Button/Button';
import { formatDate } from '../../../utils/formatting';

// Пишем:
import { Button } from '@components/Button/Button';
import { formatDate } from '@utils/formatting';

Важно: Опция paths влияет только на проверку типов TypeScript. Для реального разрешения модулей при сборке необходимо настроить алиасы и в вашем сборщике (Webpack aliases, Vite resolve.alias и т.д.).

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./.tsbuildinfo"
  }
}

{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

// package.json
{ "name": "my-app", "version": "1.0.0" }

// index.ts
import pkg from './package.json';
console.log(pkg.name);    // ✅ TypeScript знает тип
console.log(pkg.version); // ✅ Автодополнение работает

// ❌ Без strict mode этот код скомпилируется без ошибок:
function processUser(user) {
  console.log(user.name);  // Может упасть, если user = null
}

// ✅ С strict mode вы сразу увидите проблему:
// Parameter 'user' implicitly has an 'any' type.

// ❌ Если в tsconfig.json:
// "module": "commonjs"
// но в package.json:
// "type": "module"

// Результат: Node.js не сможет запустить ваш код
// потому что CommonJS и ESM несовместимы

// Без outDir:
src/
├── index.ts
├── index.js      ← скомпилированный файл рядом с исходником
├── utils.ts
└── utils.js      ← ещё один скомпилированный файл

// С outDir:
src/
├── index.ts
└── utils.ts
dist/
├── index.js
└── utils.js

// ❌ Конфликт:
{
  "noEmit": true,      // Не генерировать файлы
  "declaration": true  // Но генерировать declaration файлы
}

// ✅ Правильно для библиотеки:
{
  "noEmit": false,     // Генерировать файлы
  "declaration": true  // Включая declaration файлы
}

// ✅ Правильно для веб-приложения:
{
  "noEmit": true,      // Не генерировать файлы (собирает Vite/Webpack)
  "declaration": false // Declaration не нужны
}

// ❌ Без baseUrl paths не работает:
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

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

// ❌ Компилятор попытается скомпилировать тысячи файлов из node_modules
// Это очень медленно и вызовет кучу ошибок

// ✅ Всегда исключайте node_modules:
{
  "exclude": ["node_modules"]
}

// Или используйте include вместо exclude:
{
  "include": ["src/**/*.ts"]
}

Чек-лист перед коммитом tsconfig.json:

• Включён ли strict mode?
• Правильно ли выбран module (ESNext, commonjs, Node16)?
• Указаны ли outDir и rootDir?
• Исключены ли node_modules и dist?
• Есть ли paths — указан ли baseUrl?
• Совместимы ли noEmit и declaration?
• Соответствует ли target среде выполнения?

Что мы узнали:

• tsconfig.json — это файл конфигурации, который определяет поведение компилятора TypeScript и влияет на работу IDE
• Создать tsconfig.json можно командой tsc --init, вручную или через VS Code
• Основные опции: target (версия JS), module (система модулей), strict (строгость проверок), outDir/ rootDir (структура вывода)
• include и exclude позволяют контролировать набор компилируемых файлов
• lib определяет доступные встроенные типы (DOM, ES-модули)
• noEmit отключает генерацию файлов (для проектов с Webpack/Vite)
• declaration генерирует .d.ts файлы для библиотек
• sourceMap создаёт карты соответствия для отладки
• Полезные дополнения: noUnusedLocals, noImplicitReturns, paths, incremental
• Для монорепозиториев используется механизм extends для наследования конфигураций
• Типичные ошибки: отсутствие strict, неправильный module, забытый outDir, конфликт noEmit/declaration