Экосистема и архитектура TypeScript

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

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

Дальше: Форматы и подключение · TypeScript Server · JS-курс: monorepo и публикация · Справочник — tsconfig

---

TypeScript в продакшене — не только tsc: пакетный менеджер, типы из @types/*, сборщик (Vite, esbuild), линтер, тесты и CI. Здесь — карта экосистемы, структура репозитория, монорепозиторий с project references и проверка типов в пайплайне.

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

Обзор без учебных деталей — Обзор TypeScript в JS. Таблицы tsconfig — 301.

---

Слои экосистемы

  Исходники .ts / .tsx
        │
        ├── tsserver (IDE, tsserver)
        ├── tsc / tsc -b (проверка, emit, declarations)
        ├── bundler (Vite, esbuild, Webpack) — часто без emit tsc
        ├── ESLint (@typescript-eslint)
        └── CI: typecheck + test + build
        ▼
  JavaScript → Node / браузер

Компонент	Роль
typescript	компилятор, tsc, tsserver
@types/*	типы для JS-библиотек (DefinitelyTyped)
Bundler	сборка для браузера, tree-shaking
ESLint + Prettier	стиль и часть логических правил
Vitest / Jest	тесты с TS из коробки

---

Типичная структура одного пакета

my-app/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   └── types/
│       └── api.ts
├── dist/              # после tsc (в .gitignore)
└── tests/

package.json (фрагмент):

{
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit",
    "lint": "eslint src",
    "test": "vitest run"
  },
  "devDependencies": {
    "typescript": "~5.7.0",
    "@types/node": "^22.0.0"
  }
}

Разбор:

• Типы API выносят в src/types — контракт между слоями — 6.md.
• typecheck в CI даже если bundle делает Vite — 15.md.

---

DefinitelyTyped и @types

Библиотеки на чистом JS не несут .d.ts — типы ставят отдельно:

npm i lodash
npm i -D @types/lodash

Разбор:

• Пакеты @types/* публикуются из DefinitelyTyped.
• Современные пакеты иногда включают типы в npm ("types" в package.json) — @types не нужен.

---

Рекомендуемый стартовый стек

Инструмент	Назначение
TypeScript + strict	проверка типов
ESLint @typescript-eslint	правила TS, unused vars
Prettier	форматирование
Vitest или Jest	unit-тесты
tsc --noEmit в CI	gate на PR

Минимальный tsconfig — 9.md; политика strict — 6.md.

---

Frontend vs backend

Направление	Сборка	Типичный module
SPA (React/Vue)	Vite	ESNext + bundler resolution
Node API	tsc или tsx	NodeNext
Библиотека npm	tsc + declaration	NodeNext / ESM

Прикладные статьи: 21.md (React), 22.md (Node).

---

Монорепозиторий

Несколько пакетов в одном git-репозитории — monorepo (pnpm workspaces, npm workspaces, Nx, Turborepo).

repo/
├── package.json          # workspaces
├── tsconfig.base.json
├── packages/
│   ├── core/
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/
│   └── app/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/

Корневой tsconfig.base.json:

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "strict": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

packages/core/tsconfig.json:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

packages/app/tsconfig.json с зависимостью:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "references": [{ "path": "../core" }],
  "include": ["src"]
}

Сборка всего дерева:

tsc -b

Разбор:

• composite: true — пакет можно подключать через references.
• tsc -b (build mode) собирает граф в правильном порядке и инкрементально.
• tsserver использует тот же граф — быстрее в IDE на больших репо — 16.md.

Указатель в JS-курсе — JS-курс: monorepo и публикация. Таблицы — Справочник — tsconfig.

---

Публикация библиотеки на npm

Шаг	Действие
1	"declaration": true — генерировать .d.ts
2	"types": "dist/index.d.ts", "exports" в package.json
3	"files": ["dist"] — только артефакты
4	npm publish после tsc -b

Потребители получают типы вместе с JS — контракт API стабилен.

---

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

Пример шага GitHub Actions:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: "22"
    cache: "npm"
- run: npm ci
- run: npm run typecheck

Для monorepo:

- run: npx tsc -b

Разбор:

• typecheck должен падать PR при ошибке типов — тот же контракт, что в IDE.
• Не полагайтесь только на build bundler'а: он может пропустить отдельные файлы.

Кэширование: node_modules + incremental .tsbuildinfo при composite.

---

Разделение ответственности: tsc vs bundler

Задача	Кто
Проверка типов всего проекта	tsc --noEmit или tsc -b
Быстрый dev-server	Vite
Транспиляция в старый target	tsc или esbuild в bundler
.d.ts для библиотеки	tsc с declaration

Частый паттерн SPA: Vite собирает, tsc -b или tsc --noEmit проверяет типы (в шаблоне react-ts это шаг build перед vite build) — 15.md. Для Vue-проектов аналог — vue-tsc --noEmit.

---

Связь с разделом энциклопедии

Слой	Где
Учёба	5-10-typescript/*.md
Обзор в JS-курсе	30
Таблицы	301
Индекс	2.md — не второй справочник

---

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

Ошибка	Причина	Что делать
Нет typecheck в CI	полагались на Vite	tsc --noEmit
Версии TS расходятся	глобальный tsserver	workspace TS — 16.md
Monorepo тормозит	один tsconfig на всё	references + composite
Типы не находятся	нет @types	установить или обновить пакет
dist в git	артефакты в репо	.gitignore, files в publish
Дублирование 301 в статьях	шум	ссылка на справочник

---

Практика

1. Добавьте в учебный проект скрипт typecheck и шаг в CI (или локальный npm run typecheck перед push).
2. Вынесите типы API в src/types и импортируйте в сервисе.
3. Нарисуйте схему: IDE → tsserver → тот же tsconfig, что и CI.
4. (Опционально) Создайте два пакета core + app с references и соберите tsc -b.
5. Установите @types для одной JS-библиотеки и проверьте автодополнение.

---

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

• Подключение — ESM, tsconfig
• Компиляция — emit, source maps
• TypeScript Server — IDE
• Рекомендации — strict, Zod, миграция
• Первая программа — старт с нуля
• Справочник — 30, 301