Как мигрировать проект с JavaScript на TypeScript: Практическое руководство

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

Подготовка к миграции

Перед тем как начать, убедитесь, что ваш проект использует систему сборки, совместимую с TypeScript (например, Webpack, Vite, или просто Node.js с ES-модулями). Затем установите TypeScript и необходимые типы:

npm install --save-dev typescript @types/node

Добавьте конфигурационный файл tsconfig.json:

{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "module": "ESNext",
    "target": "ES6",
    "esModuleInterop": true,
    "allowJs": true,
    "checkJs": true
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

Поэтапное переименование файлов

Начинайте миграцию с переименования .js файлов в .ts и .jsx в .tsx. Сначала сконцентрируйтесь на файлах, которые содержат минимум динамических типов.

mv src/app.js src/app.ts
mv src/components/Button.jsx src/components/Button.tsx

TypeScript сразу начнет подсказывать ошибки типов. Вы можете временно использовать any, чтобы ускорить процесс:

function fetchData(url: string): any {
  return fetch(url).then((res) => res.json());
}

Но лучше постепенно заменять any на точные типы.

Исправление ошибок типов

После переименования файлов начнут появляться ошибки. Рассмотрим несколько типичных проблем и их решения.

Проблема 1: Неопределенные параметры

function greet(user) {
  return `Hello, ${user.name}`;
}

TypeScript выдаст ошибку Parameter 'user' implicitly has an 'any' type. Решение:

type User = { name: string };

function greet(user: User): string {
  return `Hello, ${user.name}`;
}

Проблема 2: Ошибка при импорте модулей

import express from 'express';

Если появляется ошибка Cannot find module 'express', установите соответствующие типы:

npm install --save-dev @types/express

Обработка JavaScript-файлов без изменений

Если у вас большой код, можно частично мигрировать проект, используя allowJs и checkJs в tsconfig.json. Это позволит компилятору проверять .js файлы без необходимости их переписывания.

"allowJs": true,
"checkJs": true

Такой подход удобен, если у вас много существующего кода, который трудно сразу перевести на TypeScript. Компилятор TypeScript сможет анализировать .js файлы, выявлять возможные ошибки и предупреждать о них. Например, если в JavaScript-коде используется переменная без явного объявления, TypeScript сообщит об этом, помогая устранить потенциальные проблемы.

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

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

Если в проекте используется ESLint, можно добавить правило @typescript-eslint/no-unsafe-assignment, чтобы указывать на потенциально небезопасные присваивания. Это поможет еще больше улучшить качество кода при миграции.

Улучшение типизации

После исправления основных ошибок можно заменить any на более строгие типы. Например, добавим интерфейсы для API-запросов:

interface User {
  id: number;
  name: string;
  email: string;
}

function fetchUser(id: number): Promise {
  return fetch(`/api/user/${id}`).then(res => res.json());
}

Кроме того, можно использовать Readonly<T>, Partial<T> и другие утилиты TypeScript для дополнительной безопасности:

type ReadonlyUser = Readonly<User>;

Это позволит защитить данные от нежелательных изменений.

Завершение миграции

Когда все .js файлы превращены в .ts, можно убрать allowJs и checkJs, а также настроить строгую проверку:

"strict": true

Дополнительно рекомендуется настроить CI/CD для проверки типов перед развертыванием, например, с помощью tsc --noEmit. Также стоит использовать инструмент ts-prune для поиска неиспользуемых типов.

Теперь ваш проект полностью работает на TypeScript!

Заключение

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

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

Кроме того, статическая проверка типов ускоряет процесс отладки, поскольку многие ошибки выявляются еще на этапе написания кода. Это сокращает время, затрачиваемое на исправление багов, и повышает стабильность приложения. В долгосрочной перспективе использование TypeScript уменьшает технический долг и делает кодовую базу более устойчивой к изменениям.

Хотя процесс миграции может занять некоторое время, результаты оправдывают вложенные усилия. Инструменты TypeScript, такие как автодополнение, проверка типов и улучшенные возможности рефакторинга, значительно повышают продуктивность. В результате ваша команда сможет быстрее разрабатывать функционал, с меньшими рисками и лучшим качеством кода.