Миграция с JavaScript на TypeScript

Постепенно перенести существующий проект JavaScript на TypeScript.


Стратегия миграции

  1. Добавление tsconfig.json
  2. Переименование .js в .ts
  3. Постепенное добавление аннотаций типов
  4. Включение строгого режима

Настройка tsconfig.json

tsconfig.json

{
    "compilerOptions": {
        // Начальный этап: ослабленная конфигурация
        "target": "ES2020",
        "module": "commonjs",
        "strict": false,
        "noImplicitAny": false,
        "strictNullChecks": false,
        "skipLibCheck": true,

        // Разрешить JS-файлы
        "allowJs": true,
        "checkJs": false,

        // Каталог вывода
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
}

Постепенно включайте строгие проверки

Включайте поэтапно

// Этап 1: Базовая миграция
{
    "compilerOptions": {
        "strict": false,
        "noImplicitAny": false
    }
}

// Этап 2: Включить проверку типов
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true
    }
}

// Этап 3: Полностью строгий режим
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "strictPropertyInitialization": true
    }
}

Аннотации типов JSDoc

Используйте JSDoc в JavaScript для добавления типов.

utils.js

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */

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

/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} email
 */


/**
 * @param {number} id
 * @returns {Promise<User>}
 */

function getUser(id) {
    return fetch(`/api/users/${id}`).then(r => r.json());
}

Вывод:

JSDoc 注释添加成功

Файлы деклараций типов

Создайте декларации для модулей без определений типов.

src/types/my-module.d.ts

declare module "my-module" {
    export function doSomething(param: string): void;
    export class MyClass {
        constructor(options: { name: string });
        name: string;
    }
}

Ключевое слово declare

Пример

// Объявление глобальной переменной
declare var GLOBAL_CONFIG: {
    apiUrl: string;
    version: string;
};

// Объявление глобальной функции
declare function myFunction(param: string): void;

// Объявление пространства имён
declare namespace MyNamespace {
    function doSomething(): void;
}

// Использование
console.log(GLOBAL_CONFIG.apiUrl);
myFunction("hello");
MyNamespace.doSomething();

Вывод:

Declaration successful

Инструменты миграции

  • tsc --allowJs:Компиляция JS-файлов
  • checkJs:Проверка типов JS
  • // @ts-check:Проверка типов в одном файле
  • // @ts-ignore:Игнорирование ошибок

legacy.js

// @ts-check
// @ts-ignore
var result = someLegacyFunction();

Лучшие практики

  1. Начать миграцию с критических модулей
  2. Добавить модульные тесты
  3. Постепенно включить строгий режим
  4. Использовать комментарии JSDoc
  5. Создать файлы объявлений типов

Итог

  • Инкрементальный:Пошаговая миграция
  • JSDoc:Аннотации типов
  • Файлы объявлений:.d.ts
  • Строгий режим:Включать поэтапно

Другие расширения