Настройка TypeScript для проекта Event Me

Когда мы писали учебные примеры в предыдущих уроках, TypeScript запускался локально через tsx почти без настроек. В реальном проекте так не получится: у каждого репозитория своя структура папок, своё окружение выполнения (браузер или Node.js) и свои требования к строгости проверок. Именно поэтому конфигурация не глобальная, а живёт внутри самого проекта — в файле tsconfig.json.

Event Me — это full-stack приложение, поэтому у него будут разные требования для клиентской и серверной части. Но начинать удобнее с общей базы: сначала подключаем TypeScript на уровне всего репозитория, а уже в следующих уроках будем уточнять настройки отдельно для фронтенда и бэкенда.

TypeScript нужен только на этапе разработки — конечным пользователям он не отправляется, потому что браузер и Node.js выполняют обычный JavaScript. Поэтому TypeScript устанавливается как devDependency, а не как обычная зависимость.

npm install --save-dev typescript

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

npx tsc --version

Флаг npx запускает именно локальную версию компилятора из node_modules, а не ту, что могла быть установлена на компьютере раньше. Это важно: разные проекты могут использовать разные версии TypeScript, и локальная установка гарантирует, что все участники команды работают с одной и той же версией.

Файл tsconfig.json сообщает компилятору, как именно проверять и компилировать код. Создать его вручную можно, но проще сгенерировать заготовку командой:

npx tsc --init

Эта команда создаёт файл с десятками закомментированных опций и коротким пояснением к каждой из них. Для старта достаточно оставить лишь несколько ключевых настроек, а остальное включать по мере необходимости:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Обратите внимание: мы уже встречали часть этих флагов раньше — например, target разбирали в уроке про цели компиляции, а outDir и rootDir — в уроке про входные и выходные файлы tsc. Теперь мы применяем эти знания в настоящем проекте, а не в изолированном примере.

Опций в tsconfig.json много, но на старте важно понимать смысл лишь нескольких, которые сильнее всего влияют на поведение проекта.

Список того, за чем стоит следить в первую очередь при настройке нового проекта:

1. Включён ли strict режим
2. Соответствует ли target реальной среде выполнения
3. Указаны ли корректные include и exclude
4. Не конфликтует ли module с используемым бандлером

После того как tsconfig.json создан, можно запустить проверку типов по всему проекту и посмотреть, сколько ошибок покажет компилятор:

npx tsc --noEmit

Флаг —noEmit мы уже разбирали в уроке про рабочий процесс с проверкой типов: он запускает проверку без создания JavaScript-файлов на выходе. Это удобно на этапе миграции — файлы ещё имеют расширение .js, а TypeScript уже может подсвечивать потенциальные проблемы, если включить параметр allowJs.

На первом запуске в реальном проекте компилятор почти всегда выдаёт список ошибок — это нормально. Задача не в том, чтобы исправить всё за один раз, а в том, чтобы двигаться постепенно: сначала избавиться от неявных any, затем — от несовпадений типов в функциях, и только потом переходить к более тонким случаям вроде дженериков и Omit, которые мы разбирали в упражнении на предыдущих уроках.

Сегодня мы установили TypeScript как dev-зависимость проекта Event Me, сгенерировали tsconfig.json и разобрали смысл ключевых опций компилятора — strict, target, module и других. Мы также запустили первую проверку типов с флагом --noEmit и обсудили, почему миграцию лучше проводить постепенно, а не пытаться исправить все ошибки сразу.

В следующем уроке разберём базовые конфигурации — готовые наборы настроек для типовых сред вроде Node.js и React, которые позволяют не собирать tsconfig.json вручную для каждой части проекта.