TypeScript с нуля: первый файл, типы и компиляция

TypeScript проще всего понять не через определение, а через маленькую неприятность из JavaScript. Допустим, у нас есть функция, которая считает сумму заказа. Пока код короткий, все выглядит невинно. Потом в функцию случайно прилетает строка вместо числа, и ошибка всплывает только во время запуска

TypeScript нужен как раз для таких моментов. Он не делает браузер или Node.js умнее сам по себе. Он проверяет код до запуска, показывает подозрительные места и после компиляции превращает .ts файл в обычный JavaScript

В этом уроке создадим первый TypeScript-файл, скомпилируем его через tsc, запустим результат и специально поймаем ошибку типов. Без фреймворков, React и лишней архитектуры

Что получится в конце

В конце будет маленький проект:

ts-first-step/
├─ src/
│  └─ lesson.ts
└─ dist/
   └─ lesson.js

В lesson.ts мы напишем код с типами:

const lessonTitle: string = "TypeScript";
const minutes: number = 25;
const isFinished: boolean = false;

function formatLesson(title: string, duration: number): string {
  return `${title}: ${duration} минут`;
}

console.log(formatLesson(lessonTitle, minutes));
console.log(`Готово: ${isFinished}`);

После компиляции TypeScript уберет аннотации типов и создаст обычный JavaScript. Это важный момент: типы помогают на этапе разработки, но в рантайме работает JavaScript

Что нужно заранее

Нужен установленный Node.js и npm. Если Node.js уже стоит, проверь:

node -v
npm -v

Для первого урока не нужно ставить TypeScript глобально. Лучше поставить его как зависимость проекта, чтобы версия была записана рядом с кодом. Так меньше сюрпризов, когда один проект собирается старой версией, а другой новой

Создаем папку проекта

Создай папку и перейди в нее:

mkdir ts-first-step
cd ts-first-step
npm init -y
npm install -D typescript

Флаг -D означает dev dependency. TypeScript нужен нам для разработки и компиляции, а не как библиотека, которая будет работать в браузере или на сервере

Проверь, что компилятор доступен:

npx tsc --version

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

Первый TypeScript-файл

Создай папку src и файл lesson.ts:

mkdir src

Внутрь src/lesson.ts вставь:

const lessonTitle: string = "TypeScript";
const minutes: number = 25;
const isFinished: boolean = false;

function formatLesson(title: string, duration: number): string {
  return `${title}: ${duration} минут`;
}

console.log(formatLesson(lessonTitle, minutes));
console.log(`Готово: ${isFinished}`);

Здесь уже видно главное отличие от JavaScript. После имени переменной или параметра стоит тип:

• string — строка;
• number — число;
• boolean — true или false;
• : string после скобок функции — тип результата.

TypeScript часто умеет вывести тип сам. Например, он понимает, что "TypeScript" — строка. Но в первом уроке я специально оставляю явные типы, чтобы глаз привык к синтаксису

Компилируем в JavaScript

Запусти:

npx tsc src/lesson.ts --outDir dist

Если ошибок нет, появится файл dist/lesson.js. Открой его и сравни:

var lessonTitle = "TypeScript";
var minutes = 25;
var isFinished = false;
function formatLesson(title, duration) {
    return "".concat(title, ": ").concat(duration, " минут");
}
console.log(formatLesson(lessonTitle, minutes));
console.log("\u0413\u043e\u0442\u043e\u0432\u043e: ".concat(isFinished));

Видно, что типы исчезли. В JavaScript не осталось : string, : number и : boolean. Это нормальное поведение: TypeScript проверяет и преобразует код, а не добавляет в JavaScript новый рантайм типов

Запусти результат:

node dist/lesson.js

Вывод будет примерно таким:

TypeScript: 25 минут
Готово: false

Ломаем код специально

Теперь поменяй последнюю часть файла:

console.log(formatLesson(lessonTitle, "25"));

Запусти компиляцию еще раз:

npx tsc src/lesson.ts --outDir dist

TypeScript должен показать ошибку в духе:

Argument of type 'string' is not assignable to parameter of type 'number'.

Это не занудство компилятора. Мы сами сказали, что duration должен быть числом:

function formatLesson(title: string, duration: number): string

А потом передали строку "25". JavaScript, скорее всего, это проглотил бы. TypeScript останавливает нас раньше, пока ошибка не ушла в браузер, сервер или продакшен

Почему TypeScript не запускается напрямую

Иногда новичок ожидает, что можно написать:

node src/lesson.ts

В обычной настройке так не надо. Node.js выполняет JavaScript. TypeScript сначала нужно превратить в JavaScript. Есть инструменты, которые запускают TypeScript почти напрямую для разработки, например tsx или ts-node, но для первого урока полезнее увидеть честную цепочку:

lesson.ts -> tsc -> lesson.js -> node

Когда эта цепочка понятна, React, Node.js, Vite и другие инструменты перестают казаться магией. Они делают то же самое, просто автоматизируют шаги

Нужен ли tsconfig уже сейчас

Можно продолжать компилировать один файл командой npx tsc src/lesson.ts --outDir dist. Но в нормальном проекте настройки складывают в tsconfig.json

Создай его:

npx tsc --init

На первом этапе важно знать три вещи:

• target отвечает за версию JavaScript на выходе;
• module влияет на формат модулей;
• strict включает более строгую проверку типов.

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

Частые ошибки новичка

Если npx tsc не находится, проверь, что ты действительно сделал npm install -D typescript в текущей папке

Если node dist/lesson.js пишет, что файла нет, значит компиляция не создала dist/lesson.js. Вернись к команде npx tsc src/lesson.ts --outDir dist и посмотри на ошибку выше

Если TypeScript ругается на тип, не спеши ставить any. Сначала прочитай сообщение: какой тип ожидался и какой тип пришел. В половине случаев ошибка решается не хитрым синтаксисом, а исправлением значения

Если кажется, что TypeScript слишком много требует, это нормально на старте. Он как строгий напарник на ревью: сначала раздражает, потом экономит время

Мини-задание

Добавь в файл еще одну функцию:

function calculateFinishTime(startHour: number, durationMinutes: number): string {
  const finishHour = startHour + durationMinutes / 60;
  return `Примерное время окончания: ${finishHour}`;
}

console.log(calculateFinishTime(10, 25));

Потом специально передай вторым аргументом строку:

console.log(calculateFinishTime(10, "25"));

Твоя задача — прочитать ошибку и объяснить самому себе: где ожидался number, а где пришел string

Что может быть еще интересно по этой теме

TypeScript заменяет JavaScript?

Нет. TypeScript компилируется в JavaScript. Он добавляет проверку типов и удобства разработки, но итоговый код все равно выполняется как JavaScript

Нужно ли всегда писать типы вручную?

Нет. TypeScript умеет выводить типы сам. Но в параметрах функций, структурах объектов и публичных API явные типы часто делают код понятнее

Можно ли учить TypeScript без JavaScript?

Можно, но будет тяжелее. TypeScript не отменяет основы JavaScript: функции, объекты, массивы, промисы и модули все равно нужны

Почему нельзя просто использовать any?

any отключает проверку для конкретного значения. Иногда это нужно при миграции старого кода, но если ставить any везде, TypeScript превращается в JavaScript с лишними файлами

Что почитать дальше по TypeScript

• TypeScript online: где запустить код без установки — если хочешь потрогать типы без локальной установки.
• TypeScript и JavaScript: в чем разница простыми словами — чтобы закрепить модель TS -> JS.
• interface и type в TypeScript: когда что использовать — следующий шаг после первых переменных и функций.
• tsconfig.json простыми словами: strict, target и module — когда один файл превратится в маленький проект.