TypeScript: компиляция и запуск

TypeScript-компилятор (tsc) транспилирует .ts-файлы в JavaScript, который запускается в Node.js или браузере; для разработки существуют инструменты (ts-node, tsx, esbuild) позволяющие запускать TS-код напрямую.

Зачем нужно

TypeScript не выполняется напрямую — браузер и Node.js понимают только JavaScript. Понимание процесса компиляции, вывода файлов и опций tsconfig позволяет корректно настроить проект и выбрать подходящий workflow для разработки и production.

Где используется

  • Сборка production-артефактов перед деплоем
  • Проверка типов в CI без сборки (tsc --noEmit)
  • Быстрый запуск в разработке через ts-node или tsx
  • Интеграция в bundler (Vite, webpack, esbuild)

Основной контент

Базовая компиляция через tsc

# Установка
npm install -D typescript

# Компиляция одного файла
npx tsc index.ts

# Компиляция проекта (по tsconfig.json)
npx tsc

# Только проверка типов без emit файлов
npx tsc --noEmit

# Watch mode
npx tsc --watch

Структура вывода компиляции

src/
  index.ts       → dist/index.js (+ dist/index.d.ts если declaration: true)
  utils/
    format.ts    → dist/utils/format.js

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true
  }
}

Source Maps — отладка TypeScript

{
  "compilerOptions": {
    "sourceMap": true
    // Генерирует .js.map — браузер/Node показывает TS-код при ошибках
  }
}

# Запуск с source maps в Node
node --enable-source-maps dist/index.js

ts-node — прямой запуск в разработке

npm install -D ts-node @types/node

# Запуск
npx ts-node src/index.ts

# С конфигурацией (tsconfig-paths и т.п.)
npx ts-node -r tsconfig-paths/register src/index.ts

tsx — быстрая альтернатива ts-node

npm install -D tsx

# Прямой запуск
npx tsx src/index.ts

# Watch mode
npx tsx watch src/index.ts

Компиляция для разных сред

// Для Node.js
{ "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext" }

// Для браузера (bundler сам обработает модули)
{ "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler" }

// Для библиотеки (с declaration files)
{ "target": "ES2017", "module": "CommonJS", "declaration": true, "declarationDir": "./types" }

Проверка типов в CI

# package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "tsc"
  }
}

# CI pipeline
npm run typecheck && npm test && npm run build

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

  • Запускать tsc без tsconfig.json — компилятор использует дефолтные настройки, которые могут не соответствовать проекту.
  • Коммитить dist/ в git — при наличии CI-сборки это лишнее; добавьте dist/ в .gitignore.
  • Использовать ts-node в production — он медленнее и предназначен для разработки; в production запускайте скомпилированный JS.
  • Не запускать tsc --noEmit в CI — bundler (Vite, esbuild) не делает полную проверку типов; нужен отдельный шаг.

Связанные темы

Ресурсы