Основы TypeScript: компилятор tsc и tsconfig.json

Компилятор TypeScript tsc и конфигурационный файл tsconfig.json образуют основу рабочего процесса TypeScript: первый преобразует ваш типизированный код в JavaScript, а второй диктует правила этого преобразования для всего проекта. В этом руководстве вы узнаете, как установить компилятор tsc, задавать параметры через командную строку и централизованно управлять конфигурацией проекта через tsconfig.json. Эти инструменты необходимы для преобразования TypeScript (.ts) в JavaScript (.js) и поддержания единых правил компиляции и проверки типов в проекте.

Компилятор TypeScript (tsc)

1. Что такое tsc

tsc — это компилятор TypeScript. Он преобразует код из файлов .ts или .tsx в JavaScript (.js), который может выполнять среда JavaScript. Этот процесс называется транспиляцией (transpilation). В отличие от компиляции в машинный код, tsc переводит TypeScript в эквивалентный JavaScript, сохраняя уровень абстракции, что позволяет запускать код в любой среде выполнения JS (браузер, Node.js).

2. Как установить tsc

Установите tsc глобально через npm, чтобы команда стала доступна из командной строки:

npm install -g typescript

После установки проверьте версию командой tsc --version.

3. Компиляция TypeScript кода

Чтобы скомпилировать TypeScript-файл, выполните в терминале:

tsc yourfile.ts

Рядом с yourfile.ts появится yourfile.js. Если в коде TypeScript есть ошибки типов, tsc выведет их в консоль.

4. Параметры компилятора

tsc поддерживает множество параметров (флагов) для настройки процесса компиляции. Когда вы явно указываете файл (например, tsc index.ts), вы можете передать флаги для управления его компиляцией. Например, следующая команда скомпилирует все TypeScript-файлы в текущей директории в версию ES5 и поместит результат в каталог ./dist:

tsc --target ES5 --outDir ./dist

Ключевые флаги для повседневной работы:

• --watch (-w) — запускает компилятор в режиме наблюдения, он автоматически перекомпилирует файлы при их изменении;
• --strict — включает всю строгую типизацию, рекомендуемую для новых проектов;
• --noEmitOnError — не создаёт JS-файлы, если при компиляции обнаружены ошибки типов.

Работать с флагами в командной строке удобно для разовых задач или экспериментов. Однако в реальном проекте это приводит к проблемам:

1. Несогласованность: разные разработчики (или один разработчик в разное время) могут случайно использовать разные настройки.
2. Опечатки: длинные списки флагов легко ошибиться.
3. Интеграция: инструментам сборки (Vite, Webpack) сложно автоматически подхватывать разрозненные настройки из командной строки.

Именно для этого создан файл tsconfig.json — он хранит все настройки компиляции в одном месте, гарантируя их согласованность.

tsconfig.json

1. Что такое tsconfig.json

tsconfig.json — это центральный конфигурационный файл проекта TypeScript. Его главная задача — зафиксировать единые правила компиляции и проверки типов для всей команды и инструментов сборки (Vite, Webpack). В нём задаются все параметры компилятора, указываются исходные файлы и директории для исключения.

2. Создание файла tsconfig.json

Создайте tsconfig.json вручную в корне проекта или сгенерируйте базовый вариант со множеством закомментированных опций командой:

tsc --init

3. Параметры компилятора в tsconfig.json

Основные настройки в tsconfig.json (шпаргалка):

• compilerOptions: самая важная секция, где задаются параметры компилятора (целевая версия JS, строгость проверок, пути вывода и т.д.);
• include: маски файлов для компиляции (например, ["src/**/*.ts"] для всех TypeScript-файлов в папке src и её подпапках)
• exclude: маски файлов или папок, которые компилятор должен пропустить. На практике эта настройка часто избыточна, так как компилятор по умолчанию не включает файлы из node_modules. Явно указывать exclude нужно, например, для игнорирования ваших собственных тестовых или сгенерированных файлов вроде **/*.test.ts или dist/ (если исходники и транспилированные лежат в одном проекте);
• extends: позволяет наследовать настройки от другого конфигурационного файла (удобно для монопрепозиториев).

4. Пример tsconfig.json

Ниже базовая конфигурация для старта проекта:

{
  "compilerOptions": {
      "target": "es5",
      "module": "commonjs",
      "outDir": "./dist"
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

Практическое использование tsc и tsconfig.json: от экспериментов к рабочему проекту

Понимание отдельных команд и опций — это только начало. Давайте соберём всё воедино и посмотрим, как эти инструменты работают в реальных сценариях — от быстрого тестирования идеи до настройки серьёзного проекта.

Сценарий 1: Быстрый эксперимент (глобальный tsc)

Вы читаете статью, видите интересный синтаксис и хотите его проверить. Не нужно создавать проект. Просто:

1. Создайте файл test.ts в любой папке.
2. Напишите код.
3. Выполните в терминале: tsc test.ts && node test.js.

Глобально установленный компилятор идеален для таких сиюминутных проверок. Он всегда под рукой, не требует конфигурации, и вы можете сразу увидеть результат.

Сценарий 2: Начало нового проекта (локальный TypeScript и tsconfig.json)

Вы начинаете новый проект, в котором будет более одного файла и, возможно, будет работать не только вы. Здесь глобальная установка становится риском, потому что вы сталкиваетесь с теми самыми проблемами несогласованности и интеграции, которые описаны в разделе о параметрах компилятора. Правильный путь:

1. Инициализируйте проект: npm init -y

2. Установите TypeScript локально: npm install typescript --save-dev

   Это фиксирует версию в package.json, гарантируя, что у всей команды и на сервере сборки будет одинаковый компилятор.

3. Создайте конфигурацию: npx tsc --init

   Используйте npx для запуска локально установленного компилятора. Сгенерированный файл — это ваша база для настроек.

4. Настройте под свои нужды: Откройте tsconfig.json. Минимум, что нужно сделать:

   1. Задать "outDir": "./dist", чтобы скомпилированный код не смешивался с исходным.
   2. Проверить, что "target" соответствует вашей среде выполнения (например, "es2020" для Node.js 14+).
   3. Включить строгие проверки: Найдите и раскомментируйте "strict": true,. Это главное преимущество TypeScript.

5. Добавьте скрипты в package.json:

   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch",
     "type-check": "tsc --noEmit"
   }

   Теперь вместо запоминания флагов вы и ваша команда используете понятные команды: npm run build, npm run watch.

Почему это работает? Локальная установка и tsconfig.json создают самодокументируемую и воспроизводимую среду. Новый разработчик, склонировав репозиторий и выполнив npm install, сразу получает весь нужный инструментарий с правильными настройками.

Сценарий 3: Интеграция в рабочий процесс

• Непрерывная интеграция (CI): В вашем пайплайне (GitHub Actions, GitLab CI) команда npm run type-check (или просто npx tsc --noEmit) гарантирует, что в репозиторий не попадёт код с ошибками типов.
• Совместная работа с инструментами сборки: Vite, Webpack, ESLint автоматически обнаруживают tsconfig.json в корне проекта и используют его настройки. Единый файл конфигурации становится источником истины для всей экосистемы инструментов.

Бонус: Повышение производительности в больших проектах

Когда проект разрастается, полная перекомпиляция всех файлов начинает отнимать время. Здесь на помощь приходит инкрементальная компиляция. Добавьте в tsconfig.json опцию:

"compilerOptions": {
  "incremental": true
}

Теперь компилятор будет сохранять кэш в файле .tsbuildinfo. При следующем запуске tsc пересобираться будут только изменённые файлы и их зависимости. Это особенно заметно ускоряет работу в режиме --watch и холодные старты после перезагрузки IDE.

Заключение

Вместе tsc и tsconfig.json образуют основу рабочего процесса TypeScript: компилятор выполняет преобразование кода, а конфигурационный файл задаёт правила этого преобразования. Освоив их, вы сможете:

• Эффективно преобразовывать TypeScript в JavaScript для любого окружения
• Централизованно управлять настройками компиляции во всём проекте
• Стандартизировать процесс разработки для работы в команде
• Гибко настраивать проверку типов под требования проекта

Следующий шаг: Изучите различия между JavaScript и TypeScript, чтобы глубже понять преимущества типизации.