Руководство по TypeScript: установка, миграция и лучшие практики

Быстрые ссылки

• Что такое TypeScript?

• Установка TypeScript и Webpack

• Работа с пакетами, написанными на JS

• Типизация устаревшего (legacy) кода

• Глобальные типы для проекта

• Отключение проверки noImplicitAny при крайней необходимости

Что такое TypeScript?

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

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

Пример: в динамическом JavaScript переменная может менять тип в рантайме. TypeScript запрещает передать

int

в функцию, которая ожидает

string

и благодаря этому снижает класс распространённых ошибок.

Преимущества:

• Улучшенное автодополнение и навигация в IDE.
• Больше ошибок обнаруживается на этапе компиляции.
• Явная контрактная модель для функций и компонентов.

Важно: TypeScript не делает код “безошибочным” — он даёт инструмент для раннего обнаружения проблем и улучшения поддержки командной работы.

Установка TypeScript и Webpack

Если вы создаёте новый проект React, проще всего воспользоваться шаблоном create-react-app с TypeScript:

npx create-react-app --template typescript

Это даст готовую конфигурацию. Если проект уже существует, можно постепенно переводить файлы.

Если вы настраиваете всё вручную или не используете React, выполните:

npm install --save-dev typescript
npm install -g typescript

Типичный тест: сохраните файл test.ts с содержимым:

function Hello(object: string) {
  console.log(`Hello, ${object}!`);
}

Hello('World')

Скомпилируйте tsc test.ts. Файлы TypeScript имеют расширение .ts, а для JSX — .tsx.

Интеграция с Webpack — рекомендуемый путь для проектов, где сборка уже происходит через Webpack. Установите Webpack и ts-loader:

npm install --save-dev webpack webpack-cli ts-loader source-map-loader

Минимальная конфигурация tsconfig.json для начала (создайте файл в корне проекта):

{
  "compilerOptions": {
    "outDir": "./dist/",
    "sourceMap": true,
    "skipLibCheck": true,
    "noImplicitAny": true,
    "module": "commonjs",
    "target": "es6",
    "jsx": "react"
  }
}

Пояснения к ключевым опциям:

• outDir — куда помещать результат компиляции.
• sourceMap — полезно для отладки и сопоставления с исходниками.
• skipLibCheck — ускоряет сборку, пропуская проверку типов в библиотеках.
• noImplicitAny — заставляет явно указывать типы там, где иначе будет any.
• jsx — для React-проектов укажите react (или react-jsx для новых версий).

Пример webpack.config.js, который позволяет Webpack обрабатывать .ts и .tsx:

module.exports = {
  mode: "production",
  // Enable sourcemaps for debugging webpack's output.
  devtool: "source-map",
  resolve: {
    // Add '.ts' and '.tsx' as resolvable extensions.
    extensions: [".ts", ".tsx", ".js"]
  },
  module: {
    rules: [
      {
        test: /.ts(x?)$/,
        exclude: /node_modules/,
        use: [
          {
            loader: "ts-loader"
          }
        ]
      },
      // All output '.js' files will have any sourcemaps re-processed by 'source-map-loader'.
      {
        enforce: "pre",
        test: /.js$/,
        loader: "source-map-loader"
      }
    ]
  },
  externals: {
    "react": "React",
    "react-dom": "ReactDOM"
  }
};

Советы:

• Для разработки используйте webpack-dev-server или npx webpack --watch.
• Если сборка стала медленнее, включите transpileOnly в ts-loader и используйте fork-ts-checker-webpack-plugin для фоновой типизации.
• Для monorepo и больших проектов настройте инкрементальную компиляцию (incremental: true) и tsBuildInfoFile.

Работа с пакетами, написанными на JavaScript

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

1. Установить типы из DefinitelyTyped (пакеты @types/...):

npm install --save-dev @types/react @types/react-dom

2. Если типы недоступны, можно написать декларацию вручную и поместить её в src (или в папку types), например package.d.ts:

export as namespace Package;
export = Package;

declare namespace Package {
  interface Type {
    value: boolean;
  }
  // и т.д.
}

И подключить при необходимости из файла:

///

Альтернативный и часто более простой вариант — создать модульную декларацию-«заглушку»:

declare module 'имя-пакета';

Это скажет компилятору считать пакет непрокомментированным, но без точных типов (эффективно — any). Такой подход удобен для быстрого запуска, но теряется безопасность типов.

Советы при работе с пакетами на JS:

• Ищите @types/имя-пакета сначала.
• Для больших внешних библиотек рассмотрите возможность внести вклад в DefinitelyTyped.
• В tsconfig.json временно можно включить skipLibCheck для ускорения и уменьшения шума от типов библиотек.

Типизация устаревшего (legacy) кода

Переход к TypeScript в большом проекте — это не миграция «в один присест». Рекомендуется поэтапный подход:

1. Подготовка репозитория

• Включите TypeScript как dev-зависимость.
• Настройте сборку и правила ESLint/TSLint (если используете).
• Решите, будут ли файлы мигрироваться по одному или целыми модулями.

2. Приоритезация файлов

• Начните с частей, где типы приносят максимальную пользу: общие утилиты, данные API, формы, сложные компоненты.
• Отложите низкоуровневые скрипты и тестовые утилиты на второй этап.

3. Стратегия по файлам

• Переименуйте .js → .ts или .tsx по мере необходимости.
• Добавляйте интерфейсы для props, возвращаемых значений и структур данных.
• Используйте any в качестве временной меры, но помечайте TODO, чтобы не оставить «мусор» типов.

4. Проверка и тестирование

• Поддерживайте покрытие тестами для кода, где были изменены типы.
• Прогоняйте линтер и сборку в CI до и после миграции отдельных пулл-реквестов.

Пример: компонент React на чистом JS (до миграции):

Чтобы типизировать, определите интерфейс для props и примените его к функции. Каждый используемый ключ props добавляйте в интерфейс с соответствующим типом.

Если вы забыли или не хотите типизировать сразу — можно воспользоваться комментариями-командами TypeScript:

//@ts-ignore

или в начале файла

// @ts-nocheck

Эти директивы полезны временно, но не должны оставаться навсегда.

Ключевые практики для миграции legacy кода:

• Работайте маленькими шагами; один PR = одна логическая часть.
• Добавляйте типы вокруг публичных API и границ модулей в первую очередь.
• Документируйте решения по типам в README/CONTRIBUTING.

Глобальные типы проекта

Для общих перечислений и типов удобно держать глобальный файл деклараций, например src/global.d.ts:

declare global {
  enum Color {
    primary = "#6ca583",
    accent = "#9b8dab",
  }
}

export {};

Примечание: export {} делает файл модулем и предотвращает ошибку о глобальных декларациях в некоторых конфигурациях.

Советы:

• Держите только действительно глобальные вещи в таком файле (константы окружения, типы ответов API, общие enum).
• Для домена приложения используйте отдельные namespace или модули, чтобы избежать коллизий имён.

Отключение проверки noImplicitAny при крайней необходимости

Самая частая проблема — сообщения о «Неявном any» (Implicit Any). Варианты решения:

• Явно указывать типы: val: any или val: string.
• Временно установить в tsconfig.json: "noImplicitAny": false.

Пример изменения:

{
  "compilerOptions": {
    "noImplicitAny": false
  }
}

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

Практические шаблоны и чек-листы (value add)

Ниже подборка практических артефактов, которые облегчат применение TypeScript в команде.

1. Мини-методология миграции

• Шаг 0: Добавить TypeScript в devDependencies и настроить сборку.
• Шаг 1: Типизировать shared-utils и API-слой.
• Шаг 2: Типизировать крупные компоненты UI и формы.
• Шаг 3: Дополнить тесты и CI.
• Шаг 4: Рефакторинг типов в модульной форме.

2. Дерево решений (Mermaid)

flowchart TD
  A[Начать миграцию?] --> B{Проект новый или существующий}
  B -->|Новый| C[Использовать create-react-app --template typescript]
  B -->|Существующий| D[Добавить typescript как devDependency]
  D --> E{Пакеты без типов?}
  E -->|Да| F[Искать @types/xxx или написать декларацию]
  E -->|Нет| G[Писать интерфейсы и рефакторить по PR]
  F --> G

3. Role-based checklist (для команды)

• Разработчик:
  • Переименовать один файл и добавить типы для внешних интерфейсов.
  • Оставлять TODO для временных any.
• Технический лидер:
  • Проверить tsconfig и правила линтинга.
  • Контролировать критические границы типов (API, интерфейсы).
• QA/Тестировщик:
  • Добавить тест на поведение после типизации.
• DevOps:
  • Обновить CI, включить сборку TypeScript и линтер.

4. Шаблон tsconfig для старта

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "jsx": "react",
    "strict": true,
    "noImplicitAny": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

5. Критерии приёмки

• Включён TypeScript в CI и билд без ошибок типов (или с согласованной политикой исключений).
• Ключевые API и компоненты типизированы.
• Нет незаметных // @ts-ignore в критически важных местах.

6. Риски и смягчение

• Риск: рост времени сборки. Смягчение: включить инкрементальную компиляцию и плагин для фоновой проверки типов.
• Риск: появление большого количества временных any. Смягчение: ревью PR и линтер, требующий минимального покрытия типов.
• Риск: конфликты типов при обновлении библиотек. Смягчение: закреплять версии @types и использовать CI для раннего обнаружения.

7. Короткий чек-лист для PR миграции

• Изменены расширения файлов только в пределах одной логической фичи.
• Добавлены интерфейсы для публичных контрактов.
• CI собирает проект и тесты проходят.
• [ ] Нет необоснованных @ts-ignore.

Когда TypeScript может не подойти

• Очень маленькие проекты с быстрым прототипированием, где накладные расходы по настройке перевесят выгоду.
• Скрипты-одноразовые (одноразовые миграции), где затраты на типизацию не окупаются.

Краткое резюме

TypeScript — мощный инструмент для повышения надёжности и удобства разработки. Внедряйте постепенно, контролируйте качество типов через ревью и CI, используйте DefinitelyTyped и декларации для внешних пакетов. Временные обходы вроде noImplicitAny: false и @ts-ignore допустимы, но должны быть зафиксированы и устранены в будущем.

Важно: начните с мест, где типы дают наибольшую ценность — API-слой и общие утилиты. Контролируйте процесс миграции через чек-листы и роль-ориентированные задачи.