Первая программа на TypeScript

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Архитектору

Дальше: Типы и типизация · Форматы и подключение · Компиляция · Справочник — инструменты и CLI

---

Здесь — первый рабочий проект: установка компилятора, tsconfig.json, файл .ts, сборка в JavaScript и запуск в Node.js. Цель — увидеть главное отличие от чистого JS: ошибка типов до node, а не только в runtime.

Маршрут: О разделе → Карта раздела → первая программа → Типы и типизация → Форматы и подключение.

Аналог по шагам установки на другом языке — первая программа на Python. Обзор TypeScript внутри курса JS — Обзор TypeScript в JS. Таблицы команд — Справочник — инструменты и CLI.

---

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

Требование	Назначение
Node.js LTS (20+)	npm, запуск собранного JS
Базовый JavaScript	синтаксис function, const, модули
Терминал	npx tsc, node dist/...

TypeScript не заменяет Node: вы пишете .ts, компилятор выдаёт .js, выполняет движок JavaScript. Подробнее — Компиляция и callout в intro.

---

Установка TypeScript в проект

Создайте отдельную папку для эксперимента (не обязательно внутри монорепозитория энциклопедии):

mkdir ts-hello && cd ts-hello
npm init -y
npm i -D typescript @types/node
npx tsc --init

Пакет typescript ставит компилятор tsc и типы языка. @types/node добавляет описания API Node (process, fs, …) для проверки в IDE. Команда tsc --init создаёт tsconfig.json с комментариями; для первого запуска хватит нескольких полей (ниже).

Глобальный tsc не обязателен

В проектах обычно вызывают npx tsc — версия компилятора совпадает с package.json. Глобальная установка npm i -g typescript удобна для экспериментов, но в команде фиксируют devDependency.

---

Минимальный tsconfig.json

Откройте сгенерированный файл и задайте ядро (остальное можно оставить по умолчанию или закомментировать):

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

Разбор:

Опция	Смысл
strict	включает строгую проверку (strictNullChecks, noImplicitAny, …) — рекомендации
rootDir / outDir	исходники в src/, результат в dist/
module: NodeNext	ESM/CJS по правилам Node 20+ — подробнее в 9.md

Полный справочник флагов — Справочник — tsconfig, не дублируйте его здесь.

---

Первая типизированная программа

src/index.ts:

function greet(name: string): string {
  return `Привет, ${name}!`;
}

const message: string = greet("TypeScript");
console.log(message);

Сборка и запуск:

npx tsc
node dist/index.js

Ожидаемый вывод в терминале:

Привет, TypeScript!

Разбор:

• name: string — параметр должен быть строкой (или значением, совместимым со string).
• : string после ) — тип возвращаемого значения; return 42 вызовет ошибку компиляции.
• Аннотация у message необязательна (тип выводится), но на первых шагах она помогает привыкнуть к синтаксису.

---

Первая осмысленная ошибка типов

Измените вызов:

const broken = greet(42);

Запустите npx tsc. Компилятор сообщит, что number не подходит к string — до запуска node.

Разбор:

• В чистом JavaScript такой вызов часто собирается и ломается позже (или даёт неожиданную конкатенацию).
• TypeScript переносит часть проверок на этап редактора и CI — это и есть смысл раздела 10.md.

Откройте тот же файл в VS Code / Cursor: подчёркивание и подсказка появятся без tsc, через TypeScript Server — 16.md.

---

Структура папок проекта

ts-hello/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
└── dist/          ← после tsc (в .gitignore)
    └── index.js

Добавьте в .gitignore:

node_modules/
dist/

Разбор:

• В репозиторий коммитят исходники .ts, а не обязательно dist/ (зависит от деплоя).
• dist/ пересоздаётся командой npm run build.

---

Скрипты в package.json

{
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "start": "node dist/index.js",
    "dev": "tsc --watch"
  }
}

Скрипт	Назначение
build	компиляция в dist/
typecheck	только проверка, без файлов на диске — удобно в CI
dev	пересборка при сохранении

Разбор:

• tsc --noEmit полезен, когда JS собирает Vite или esbuild, а типы проверяет отдельный шаг — см. 15.md.

---

Расширение примера: несколько модулей

src/math.ts:

export function add(a: number, b: number): number {
  return a + b;
}

src/index.ts:

import { add } from "./math.js";

console.log(add(2, 3));

Разбор:

• При module: NodeNext в импорте указывают расширение .js, хотя файл на диске — .ts: так резолвится скомпилированный модуль в Node ESM.
• Экспорт/импорт — тот же синтаксис, что в современном JS; типы проверяются на границе модулей.

---

Альтернатива: Vite + React + TypeScript

Если цель — браузерный UI, быстрее стартовать с шаблоном:

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

Разбор:

• Шаблон уже содержит tsconfig, типы React, dev-server и hot reload.
• Типы проверяются при сборке; в браузер попадает JS.
• Путь через tsc (выше) помогает увидеть цепочку компиляции; Vite прячет детали за пресетом — 21.md.

---

Быстрый запуск без dist/: tsx

tsx — runtime для TypeScript в Node.js: запуск .ts / .tsx без предварительной сборки в dist/ (внутри — быстрая трансформация, обычно через esbuild).

npm i -D tsx
npx tsx src/index.ts

Разбор:

• Удобно для локальной разработки, скриптов, разовых утилит и тестов — см. Node.js §dev.
• Не заменяет production-пайплайн: на сервере и в CI по-прежнему tsc + node dist/… или bundle.
• tsx не предназначен для публикации статического сайта: GitHub Pages и CDN отдают готовый JavaScript, не исходный TS.

TypeScript на GitHub Pages и статике

Сценарий	Что нужно	Примечание
Статический сайт (React, Vue, чистый TS)	Сборщик: Vite, Next static export, Webpack	В репозиторий попадает dist/ или build/, не .ts
Node.js API / SSR на сервере	Vercel, Railway, Render и т.д.	GitHub Pages не запускает Node — только статические файлы
Локальный прототип Node	tsx, ts-node	Только dev; в проде — скомпилированный JS

Типичная цепочка для SPA на TypeScript:

  src/*.tsx  ──npm run build──►  dist/*.js  ──deploy──►  GitHub Pages

Минимальный фрагмент index.tsx (точка входа React) — в 21.md. В CI: npm ci → npm run build → публикация каталога dist (например, action peaceiris/actions-gh-pages с publish_dir: ./dist). Подробнее про экосистему сборки — 3.md.

В учебных и боевых проектах разделяют: typecheck (tsc --noEmit) + bundle (Vite) + deploy артефакта, а не исходников.

---

Что проверить после первого запуска

Проверка	Ожидание
npx tsc	exit code 0, в dist/ есть .js
node dist/index.js	вывод без ошибок
Намеренная ошибка типа	IDE и tsc показывают проблему
npm run typecheck	падает при ошибке, даже без dist/

Если tsc молчит, а IDE ругается — сравните версию TS в проекте и в редакторе (команда TypeScript: Select Workspace Version).

---

TypeScript и JavaScript: один runtime

  .ts  ──tsc──►  .js  ──node/браузер──►  выполнение
        ↑
   типы исчезают

Вопрос	Ответ
Нужен ли отдельный движок TS?	Нет, только tsc (или аналог) + JS-runtime
Где живут типы?	Только при компиляции и в IDE
Можно ли смешивать .js и .ts?	Да, постепенная миграция — 6.md

---

Инструменты и CLI

Базовые команды компилятора и проверки — первый слой Справочник — инструменты и CLI.

Команда	Назначение
npx tsc --init	Создать tsconfig.json
npx tsc	Сборка по tsconfig → outDir
npx tsc --noEmit	Только проверка типов (CI)
npx tsc -b	Сборка monorepo с project references
npx tsc --watch	Пересборка при изменении файлов
npx tsc --showConfig	Показать итоговый конфиг после extends

Скрипты в package.json:

{
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "dev": "tsc --watch"
  }
}

Смежные инструменты (не заменяют tsc, а дополняют):

Инструмент	Роль
TypeScript Playground	эксперименты без проекта
ESLint + @typescript-eslint	стиль и часть логических правил — 3.md
Prettier	форматирование
Vitest / Jest	тесты с TS
tsserver (в IDE)	подсказки в реальном времени — 16.md

В frontend часто: typecheck через tsc, бандл через Vite — 9.md, 15.md.

---

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

Ошибка	Причина	Что делать
Cannot find module при импорте	неверное расширение / moduleResolution	сверить 9.md, для NodeNext — .js в import
tsc не создаёт dist/	нет outDir или ошибки компиляции	исправить ошибки, проверить rootDir
IDE не подсвечивает ошибки	не та версия TS	workspace TS из node_modules
node dist/index.js — Cannot find module	не собрали или неверный путь	сначала npx tsc
Сборка зелёная, runtime падает	логика, не типы	типы не заменяют тесты и валидацию API — 6.md

---

Практика

1. Соберите проект ts-hello с greet и запустите dist/index.js.
2. Добавьте функцию repeat(text: string, times: number): string и вызов с неверным типом — исправьте по сообщению tsc.
3. Вынесите add в отдельный модуль и импортируйте в index.ts (с расширением .js при NodeNext).
4. Добавьте скрипты build, typecheck, dev в package.json.
5. Создайте ветку с strict: false, сравните поведение на greet(42) — верните strict: true.

---

Смежные статьи

• Типы данных и типизация — примитивы, union, narrowing
• Форматы и подключение — ESM/CJS, пути, @types
• Рекомендации — strict, миграция с JS
• Архитектура компиляции — tsc vs bundler, source maps
• TypeScript Server — LSP в IDE
• Справочник раздела — маршрут по 301
• Обзор в курсе JS: Обзор TypeScript в JS