TypeScript для JS-разработчика: как подключить и что выбрать

У вас есть JS-проект, и вы решили добавить типы. Дальше начинается развилка: одни туториалы советуют ставить tsc и писать конфиг руками, другие — Vite, третьи вообще предлагают не компилировать, а держать типы в JSDoc-комментариях. Все варианты рабочие, но платите вы за них по-разному: скоростью сборки, размером конфига, совместимостью с текущим билдом. Разберём четыре подхода на TypeScript 5.x и Node.js 20+, у каждого назовём цену и подскажем, когда он ваш.

Что вообще делает TypeScript

TypeScript — это надстройка над JavaScript: вы пишете обычный JS плюс аннотации типов, а компилятор проверяет, что вы не передаёте строку туда, где ждут число, и выдаёт ошибку до запуска. В браузере и в Node.js TypeScript не выполняется — его сначала превращают в JS. Вопрос «как подключить TS» на 90% сводится к вопросу «чем и как компилировать».

Важно развести две задачи, которые часто путают:

• Проверка типов — поиск ошибок. Этим занимается только tsc (компилятор из пакета typescript) или редактор через тот же движок.
• Сборка — превращение .ts в .js. Этим может заниматься tsc, а может esbuild, SWC, Vite — они удаляют типы, но не проверяют их.

Отсюда растёт половина недоразумений: сборка через Vite проходит, а типы при этом кривые, потому что Vite их не смотрит. Держите это в голове, когда будете выбирать.

Вариант 1. Голый tsc — компилятор и ничего лишнего

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

npm install --save-dev typescript
npx tsc --init

Команда tsc --init создаёт tsconfig.json с закомментированными опциями. Минимум, с которого стоит начать:

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

Дальше npx tsc берёт всё из src и кладёт .js в dist. Для режима разработки — npx tsc --watch.

Что выигрываете: проверка типов и сборка одним инструментом, поведение полностью предсказуемо, минимум зависимостей. Для библиотек и небольших Node-сервисов этого достаточно.

Чем платите: tsc медленный на больших проектах — он реально проверяет типы, а это дорого. Никакого dev-сервера с горячей перезагрузкой для фронтенда из коробки нет.

Вариант 2. Vite — если это фронтенд

Для браузерного приложения tsc как сборщик почти никто не берёт: нужен dev-сервер, бандлинг, обработка CSS и ассетов. Vite делает всё это, а типы срезает через esbuild — быстро, но без проверки.

npm create vite@latest my-app -- --template vanilla-ts
cd my-app
npm install
npm run dev

Шаблон vanilla-ts даёт TypeScript без фреймворка. Есть и react-ts, vue-ts и другие. Vite поднимает dev-сервер, вы правите .ts — страница обновляется мгновенно.

Vite не скажет вам, что тип неправильный. Он молча выкинет аннотации и соберёт JS. Проверку типов вешают отдельной командой — tsc --noEmit в скрипте build или в CI, иначе ошибки типов доедут до продакшена.

Отсюда типичный package.json-скрипт: "build": "tsc --noEmit && vite build". Флаг --noEmit означает «только проверь, файлы не создавай» — генерацию берёт на себя Vite.

Что выигрываете: быстрая сборка, горячая перезагрузка, готовая обвязка для фронтенда.

Чем платите: нужна отдельная команда на проверку типов, иначе теряется главный смысл TS. Плюс лишний слой конфигурации сборщика.

Вариант 3. tsx или ts-node — запускать TS напрямую

Для Node-скриптов и бэкенда бывает лень собирать в dist ради каждого запуска. Тогда берут раннер, который компилирует на лету. Сейчас чаще ставят tsx (на базе esbuild) — он заметно быстрее старого ts-node.

npm install --save-dev tsx
npx tsx src/index.ts

Файл запускается сразу, без промежуточного .js. Для разработки удобно: tsx watch src/index.ts перезапускает при изменениях.

Отдельно отмечу: Node.js в свежих версиях умеет запускать .ts и сам, срезая типы, но набор поддерживаемых конструкций и флаги менялись от версии к версии. Прежде чем полагаться на встроенный запуск, сверьтесь с документацией именно вашей версии Node — не считайте, что «раз где-то работало, значит работает везде».

Что выигрываете: нулевой цикл сборки в разработке, быстрый старт.

Чем платите: tsx, как и Vite, типы не проверяет — это тоже esbuild. Проверку всё равно делаете через tsc --noEmit. Для продакшена этот раннер обычно не используют, там собирают заранее.

Вариант 4. JSDoc — типы без TypeScript-файлов

Если ломать сборку и переименовывать все файлы в .ts не хочется, типы можно писать прямо в JS через JSDoc-комментарии. Движок проверки у них тот же, что у TS.

// @ts-check

/**
 * @param {number} width
 * @param {number} height
 * @returns {number}
 */
function area(width, height) {
  return width * height;
}

Строка // @ts-check включает проверку для конкретного файла. Или включите её на весь проект в tsconfig.json опцией "checkJs": true" вместе с "allowJs": true", и запускайте tsc --noEmit для проверки. Файлы остаются .js, сборка не меняется вообще.

Что выигрываете: ноль изменений в билде, постепенное внедрение файл за файлом, редактор подсказывает типы.

Чем платите: синтаксис JSDoc многословнее, сложные типы (дженерики, условные типы) писать в комментариях неудобно. Подходит как переходный этап, а не как цель.

Сравнение подходов

Когда что выбирать

• Пишете фронтенд с нуля — Vite с шаблоном на нужный фреймворк плюс tsc --noEmit в CI. Это дефолт для браузерного кода.
• Библиотека или пакет в npm — tsc: он же соберёт, он же сгенерирует файлы деклараций .d.ts (опция "declaration": true), которые нужны потребителям пакета.
• Node-сервис или CLI — tsx в разработке для быстрого цикла, tsc для сборки продакшен-артефакта.
• Большой живой JS-проект, ломать сборку нельзя — начните с JSDoc и checkJs, переводите модули в .ts постепенно.

Общий принцип: инструмент для сборки выбирайте по типу проекта, а проверку типов держите отдельной командой tsc --noEmit и вешайте её на CI. Тогда быстрый сборщик не даст типам протухнуть.

Что ломается чаще всего

• Собралось, но типы кривые. Виновата иллюзия, что сборщик проверяет типы. Vite, tsx, esbuild, SWC — не проверяют. Добавьте tsc --noEmit.
• Cannot find module или ошибки с расширениями. При "module": "NodeNext" в импортах внутри проекта нужно указывать расширение .js (не .ts) — это требование ESM в Node. Непривычно, но так задумано.
• strict сыплет сотнями ошибок на старом коде. Ожидаемо: strict включает жёсткие проверки. На миграции временно отключите часть флагов и включайте по одному.
• Редактор показывает одни ошибки, tsc — другие. Редактор и tsc могут брать разные версии TypeScript. В VS Code выберите «Use Workspace Version», чтобы обе брали версию из проекта.

Что делать дальше

Определитесь с типом проекта и выберите сборщик по таблице выше. Затем настройте tsconfig.json со strict: true с самого начала — включать строгость на большом проекте потом больно. Добавьте в CI шаг tsc --noEmit, чтобы проверка типов не зависела от того, помнит ли о ней разработчик. Следующее, к чему стоит вернуться, — настройка алиасов путей (paths) и генерация деклараций, но это уже отдельная тема, здесь мы разбирали только выбор способа подключения.