Установка и три способа запустить .ts

TypeScript ставится в проект как любая другая зависимость разработки: npm install -D typescript. Флаг -D здесь по делу — в готовую сборку компилятор не уезжает, он делает свою работу до запуска и на этом заканчивается. После установки в node_modules/.bin появляется команда tsc, TypeScript Compiler.

Звать её нужно через npx tsc или через скрипт в package.json: и то и другое берёт бинарник из node_modules текущего проекта. Глобальная установка выглядит удобнее ровно до того дня, когда у вас на машине шестая версия, а в lock-файле проекта пятая, — и вы видите ошибки, которых не видит сборка на сервере, или наоборот. Версия компилятора — такая же часть проекта, как версия любого пакета; тот же довод, что и про lock-файл в главе про npm.

У pnpm и yarn те же команды с другим префиксом: pnpm add -D typescript и pnpm exec tsc, yarn add -D typescript и yarn tsc.

Первый файл на TypeScript выглядит как обычный JavaScript, которому дописали пару слов после двоеточия. Всё, что вы писали в частях I и II, остаётся валидным кодом: TypeScript — надстройка, а не другой язык.

// TypeScript — это JavaScript плюс аннотации после двоеточия
function greet(name: string, times: number): string {
  return (name + "! ").repeat(times).trim();
}

console.log(greet("Привет", 3));

Компилятор промолчал — значит, придраться было не к чему. И ещё одно: диагностики, которые вы будете видеть под примерами, не нарисованы в тексте — их выдаёт настоящий компилятор, и по-русски он говорит потому, что везёт переводы с собой. Только версия у него не та, что вы сейчас поставили. Сегодня npm ставит TypeScript 7 — нативный компилятор. Песочница учебника работает на 6.0.3: ей нужен JS API, чтобы звать компилятор прямо в браузере, а у седьмой версии такого API в прежнем виде нет. Ошибки в самих программах у двух версий те же — с теми же кодами и смыслом, так что ошибку из песочницы вы узнаете в своём терминале по коду: там tsc по умолчанию говорит по-английски.

Компилятору надо знать, какие файлы брать, во что их превращать и насколько придираться. Всё это лежит в tsconfig.json в корне проекта, а заготовку делает npx tsc --init.

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

Разбирать каждую строчку сейчас незачем — настройке проекта отведена своя глава в конце части. Одна строка, впрочем, стоит того, чтобы потрогать её сразу: strict. Вот параметр без аннотации.

function greet(name) {
  return "Привет, " + name.toUpperCase();
}

console.log(greet("Рико"));
console.log(greet(42));

TS7006 появилась не сама по себе — её включил strict. Без него компилятор молча приписал бы параметру тип any, и вторая строка упала бы в рантайме без единого предупреждения. В песочнице учебника strict включён всегда — ровно как в свежем tsconfig.json.

Классический маршрут в две команды: npx tsc превращает src/app.ts в dist/app.js, а node dist/app.js его выполняет. Компилятор делает здесь две работы — проверяет типы и выдаёт JavaScript. Независимые в самом буквальном смысле: вторая не отменяется из-за первой.

type Rub = number;

function sum(items: readonly Rub[]): Rub {
  return items.reduce((acc, item) => acc + item, 0);
}

console.log(sum([100, 200, "300"]));

Ошибка TS2322 — и всё равно 300300. Строка приклеилась к числу, потому что reduce ничего не знает о типах: до запуска доехал обычный JavaScript со сложением через +, а это тот самый оператор из главы про преобразование типов, который при виде строки бросает арифметику и начинает склеивать.

В терминале происходит ровно то же: tsc напечатает ошибку, вернёт код выхода 2 — и всё-таки положит app.js на диск. Это осознанное решение, а не недосмотр: типы не должны мешать вам запустить наполовину дописанный код. Нужно обратное — есть настройка "noEmitOnError": true, с ней при ошибке файлы не пишутся.

Код выхода важнее файла: по нему CI понимает, что сборка провалилась. Глазами в терминал на сервере никто не смотрит.

Пересобирать руками после каждого сохранения незачем: npx tsc --watch держит компилятор запущенным и перепроверяет только то, что изменилось. Это же делает ваш редактор — в нём внутри крутится тот же компилятор, только без выдачи файлов.

С версии 22.6 Node умеет открывать .ts-файлы сам — сначала под флагом --experimental-strip-types, а начиная с 22.18 и 23.6 без всяких флагов. node app.ts просто работает. Слово в названии флага важнее, чем кажется: strip — «содрать». Node не компилирует ваш файл, а вычёркивает из него всё, что относится к типам, и отдаёт движку то, что осталось.

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

А вот проверки типов нет никакой. Совсем. Файл с десятком ошибок запустится так же бодро, как безупречный. Зато на таком запуске хорошо видно, что от типов остаётся после стирания.

type Role = "admin" | "user";
const role: Role = "admin";

console.log(role);
console.log(Role);

Из правила «типы стираются» есть исключения — куски синтаксиса TypeScript, которые стереть нельзя, потому что они порождают настоящий работающий код. Самый известный — enum.

enum Status {
  Draft,
  Published
}

console.log(Status.Draft);
console.log(Status[0]);
console.log(typeof Status);

После компиляции Status — живой объект с обратным отображением: по имени достаётся число, по числу — имя. Такое не вычёркивается, такое генерируется. Поэтому node app.ts на этой строке останавливается с ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX: TypeScript enum is not supported in strip-only mode. Тот же отказ ждёт namespace и параметры-свойства вроде constructor(private name: string) — полный список разбирается в главе про классы.

Чтобы такой синтаксис не пробрался в проект незаметно, у компилятора есть флаг erasableSyntaxOnly: с ним enum и namespace становятся ошибкой TS1294 ещё на проверке.

Третий способ вы встретите чаще двух первых, хотя запускать .ts руками при этом не будете ни разу. Vite, Next, esbuild принимают .ts на вход. Сам файл внутри них переводит компилятор файла — Oxc в Vite, SWC в Next, а esbuild умеет и перевести файл, и собрать бандл. И все они делают с типами ровно то же, что Node: стирают. Это не недоделка, а решение о скорости: стирание — один проход по файлу, а проверка требует построить всю программу целиком, со всеми импортами, и обойти её.

Отсюда практический вывод, ради которого написана вся статья: если сборкой занимается не tsc, проверка типов становится отдельной командой. Её кладут в package.json под именем вроде typecheck — это tsc --noEmit — и обязательно зовут в CI рядом с тестами. Иначе типы превращаются в комментарии: написаны красиво, не читает никто.

И последнее, о чём стоит договориться сразу. Даже tsc — единственный из трёх, кто действительно проверяет, — проверяет текст программы, а не данные, которые в неё придут.

const raw: unknown = { name: "Рико" };

const user = raw as { name: string; age: number };

console.log(user.name);
console.log(user.age.toFixed(0));

Компилятор промолчал: as — не проверка, а обещание. Вы сказали «поверь, здесь такой тип», он поверил. Дальше типы стёрлись, и отвечать за них в рантайме некому — получите обычный TypeError, из тех, что вы ловили ещё в части I. Где проходит граница между «компилятор знает» и «мы надеемся» — тема отдельной главы ближе к концу части, а разбор самого as — в статье «as и @ts-expect-error: когда вы врёте компилятору». Пока запомните симптом: там, где написано as, проверок больше нет.