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

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

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

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

---

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

Следующие шаги после обзора:

• Форматы и подключение — tsconfig, ESM и CJS
• Архитектура компиляции — emit, source maps
• Обзор TypeScript в JS — краткий указатель в курсе JavaScript
• Справочник по TypeScript — таблицы tsconfig

---

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

  Исходники .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 из коробки

---

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

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

my-app/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # точка входа
│   ├── types/            # общие контракты (api, domain)
│   ├── services/         # бизнес-логика
│   └── utils/            # чистые функции без IO
├── dist/              # после tsc (в .gitignore)
└── tests/

Каталог / файл	Назначение
src/index.ts	точка входа приложения или реэкспорт публичного API
src/types/	DTO, domain, shared unions — Рекомендации §структура
src/components/ (frontend)	UI; props рядом с компонентом или в types/ui.ts
tsconfig.json	границы проекта для tsc и IDE
dist/	скомпилированный JS (не коммитить)
*.d.ts в корне	глобальные декларации (global.d.ts) — Подключение

Frontend (Vite/React) часто добавляет src/main.tsx, src/App.tsx, vite.config.ts. Backend (Node) — src/routes/, src/controllers/. Принцип тот же: типы отдельно от runtime, вход одна точка, тесты зеркалят структуру src/.

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 — контракт между слоями — Рекомендации по разработке на TypeScript.
• typecheck в CI даже если bundle делает Vite — Архитектура компиляции TypeScript и runtime.

---

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 — Форматы и подключение TypeScript; политика strict — Рекомендации по разработке на TypeScript.

---

Frontend и backend

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

Прикладные статьи: TypeScript и React (React), TypeScript и Node.js (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 на больших репо — TypeScript Server.

Указатель в 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 и 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) — Архитектура компиляции TypeScript и runtime. Для Vue-проектов аналог — vue-tsc --noEmit.

---

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

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

---

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

Ошибка	Причина	Что делать
Нет typecheck в CI	полагались на Vite	tsc --noEmit
Версии TS расходятся	глобальный tsserver	workspace TS — TypeScript Server
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, миграция
• Первая программа — старт с нуля
• Справочник — TypeScript, Справочник по TypeScript