Tsconfig.json простыми словами: strict, target и module

tsconfig.json часто пугает сильнее самого TypeScript. Открываешь файл, а там target, module, moduleResolution, strict, lib, jsx, skipLibCheck, noEmit. Кажется, что без знания всех опций проект лучше не трогать

Хорошая новость: для старта не нужно понимать весь справочник. Нужно понять несколько опций, которые реально влияют на первый учебный проект: какие файлы проверять, насколько строго проверять типы и какой JavaScript получать на выходе

В этом уроке соберем минимальный tsconfig.json и разберем его человеческим языком

Что получится в конце

Для простого проекта можно начать с такого файла:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist",
    "rootDir": "src",
    "skipLibCheck": true
  },
  "include": ["src"]
}

Это не универсальная настройка на все случаи жизни. Это нормальная отправная точка для Node.js/TypeScript-проекта. Для React, Next.js или другой сборки шаблон может отличаться, потому что сборщик берет часть работы на себя

Как создать tsconfig

В проекте с установленным TypeScript запусти:

npx tsc --init

TypeScript создаст tsconfig.json. Современные версии могут генерировать довольно подробный файл с комментариями. Это удобно для подсказок, но новичку иногда проще начать с маленькой версии и добавлять опции осознанно

include: какие файлы проверять

Опция include говорит TypeScript, где искать исходники:

{
  "include": ["src"]
}

Это значит: проверяй файлы внутри src

Если не ограничить область, TypeScript может начать смотреть туда, куда не нужно: сборочные папки, старые файлы, случайные примеры. Поэтому в учебном проекте удобно держать код в src

rootDir и outDir

rootDir — где лежит исходный TypeScript:

"rootDir": "src"

outDir — куда складывать JavaScript после компиляции:

"outDir": "dist"

Тогда схема понятная:

src/index.ts -> dist/index.js

В проектах, где TypeScript используется только для проверки типов, может стоять noEmit: true, и JavaScript вообще не создается. Например, в React-проектах сборку часто делает Vite или Next.js

strict: включать или нет

Я бы включал:

"strict": true

strict включает семейство строгих проверок. TypeScript начинает сильнее следить за null, undefined, параметрами функций и другими местами, где легко ошибиться

Да, сначала ошибок будет больше. Но это не "TypeScript мешает". Это TypeScript показывает места, которые раньше были просто неоговоренными

Если проект старый и написан на JavaScript, включить strict за один вечер может быть больно. Но для нового учебного проекта лучше сразу привыкать к строгому режиму

target: какой JavaScript получится

target отвечает за версию JavaScript на выходе:

"target": "ES2022"

Если поставить очень старый target, TypeScript будет сильнее преобразовывать современный синтаксис. Если поставить современный target, итоговый JavaScript будет ближе к исходному коду

Для Node.js-проектов можно выбирать современный target, если ты знаешь, что запускаешь код на свежей версии Node. Для браузеров выбор зависит от поддержки нужных браузеров и сборщика

Простое правило для новичка: не меняй target наугад. Если проект создан шаблоном, сначала оставь настройку шаблона

module и moduleResolution

module отвечает за формат модулей:

"module": "NodeNext"

В Node.js-мире сейчас часто встречаются CommonJS и ES Modules. Из-за этого тема модулей может быть неприятной. NodeNext говорит TypeScript ориентироваться на современные правила Node.js

Рядом обычно ставят:

"moduleResolution": "NodeNext"

Это влияет на то, как TypeScript ищет импортируемые файлы и пакеты

Для React-проекта через Vite ты можешь увидеть другие значения, например module: "ESNext" и moduleResolution: "Bundler". Это нормально: там модули обрабатывает сборщик

skipLibCheck

Частая опция:

"skipLibCheck": true

Она пропускает проверку типов внутри файлов деклараций библиотек. Это ускоряет проверку и часто избавляет от чужих конфликтов в node_modules

Для учебного проекта это допустимо. Смысл не в том, чтобы проверять каждую внешнюю библиотеку, а в том, чтобы держать свой код аккуратным

noEmit: проверять, но не собирать

Иногда TypeScript нужен только как проверка:

"noEmit": true

Тогда tsc не создает JavaScript. Это типично для проектов, где сборка идет через Vite, Next.js, Webpack или другой инструмент

Например:

npx tsc --noEmit

Команда проверит типы и ничего не запишет в dist

Минимальный tsconfig для учебного Node.js

Если делаешь простой Node.js-проект:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist",
    "skipLibCheck": true
  },
  "include": ["src"]
}

Проверка:

npx tsc

Запуск результата:

node dist/index.js

Минимальный смысл для React-проекта

В React-проектах tsconfig часто создает шаблон. Не надо сразу переписывать его руками. Лучше понять смысл:

• jsx связан с JSX-разметкой;
• strict включает строгую проверку;
• moduleResolution может быть настроен под bundler;
• noEmit часто включен, потому что сборщик сам делает итоговые файлы.

Если проект работает, не меняй module и target просто потому, что увидел другой пример в статье

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

Первая ошибка — копировать чужой tsconfig без понимания, под Node.js он или под React

Вторая ошибка — выключать strict, чтобы исчезли ошибки. Иногда это временная мера для старого проекта, но для нового кода лучше исправить причины

Третья ошибка — ожидать файл в dist, когда включен noEmit

Четвертая ошибка — менять module и получать странные проблемы с import/export. Если проект создан шаблоном, держись шаблона

Мини-задание

Создай src/index.ts:

type Lesson = {
  title: string;
  minutes: number;
};

const lesson: Lesson = {
  title: "tsconfig",
  minutes: 20,
};

console.log(lesson);

Добавь tsconfig.json с rootDir, outDir, strict. Запусти:

npx tsc
node dist/index.js

Потом поставь noEmit: true и проверь, что JavaScript больше не создается

Что может быть еще интересно по этой теме

Нужно ли помнить все опции tsconfig?

Нет. Важно понимать базовые: include, strict, target, module, rootDir, outDir, noEmit

Почему в React tsconfig отличается от Node.js?

Потому что React-проект обычно собирает bundler. Node.js-проект может компилироваться через tsc напрямую

Можно ли выключить strict?

Можно, но для нового проекта лучше не выключать. Strict помогает раньше ловить ошибки, особенно с null и undefined

Что делать, если import/export сломались?

Сначала проверь module, moduleResolution и "type" в package.json. Не смешивай настройки из разных шаблонов без причины

Что почитать дальше по TypeScript

• TypeScript с нуля: первый файл, типы и компиляция — если хочется еще раз пройти путь .ts -> .js.
• TypeScript в Node.js: первый Express API — практический пример, где tsconfig действительно нужен.
• Ошибки TypeScript: any, unknown, never и strict — чтобы понимать, какие ошибки усиливает строгий режим.
• TypeScript в React: props, state и события — пример проекта, где сборщик часто управляет компиляцией.