Codemod для автоматической миграции

Codemod — это инструмент для автоматической модификации кода, используемый для облегчения процесса миграции между версиями библиотек. В контексте Ant Design он особенно полезен при переходе с одной крупной версии на другую, когда ручное исправление сотен компонентов становится непрактичным.

Принцип работы Codemod

Codemod использует AST (Abstract Syntax Tree) для анализа исходного кода. AST представляет код в виде дерева, где каждая ветвь соответствует синтаксической конструкции JavaScript. Это позволяет инструменту:

  • Автоматически находить устаревшие компоненты;
  • Менять имена свойств и компонентов;
  • Обновлять синтаксис и API, соответствующие новой версии Ant Design.

Использование AST обеспечивает точность изменений и минимизирует риск ошибок по сравнению с простым поиском и заменой строк.

Установка и настройка

Для работы с Codemod в проекте на Ant Design достаточно установить официальные пакеты:

npm install @ant-design/codemod -D

Структура каталогов codemod обычно выглядит следующим образом:

codemod/
 ├─ v4-to-v5/
 │   ├─ button.js
 │   ├─ form.js
 │   └─ table.js
 └─ utils/
     └─ helper.js

Каждый скрипт отвечает за миграцию конкретного компонента или группы компонентов.

Основные сценарии использования

  1. Обновление компонентов

Codemod автоматически преобразует устаревшие компоненты в новые версии. Например, изменение структуры кнопок:

// До
<Button type="primary" htmlType="submit">Отправить</Button>

// После применения codemod
<Button type="primary" htmlType="submit">Отправить</Button>

В этом примере может быть заменен устаревший API или атрибуты, которые изменились в новой версии.

  1. Переименование свойств

Некоторые свойства компонентов изменяются между версиями. Codemod позволяет автоматически их переименовать, исключая необходимость ручного поиска по всему проекту.

// До
<FormItem label="Имя" required />

// После
<Form.Item label="Имя" required />
  1. Удаление deprecated API

Codemod может удалять или заменять устаревшие методы и свойства. Это особенно важно для компонентов, чьи методы больше не поддерживаются в новой версии Ant Design.

Запуск codemod

Codemod обычно запускается через CLI с указанием каталога исходного кода и конкретного скрипта миграции:

npx @ant-design/codemod v4-to-v5 ./src

Пояснение параметров:

  • v4-to-v5 — набор скриптов для миграции с версии 4 на 5;
  • ./src — директория с исходным кодом приложения.

Дополнительно можно использовать флаг --dry для тестового прогонки, чтобы увидеть изменения без их применения.

Настройка кастомных скриптов

Иногда стандартных codemod-скриптов недостаточно для крупных проектов. В таком случае можно создавать свои скрипты на основе jscodeshift:

npm install jscodeshift -D

Пример простого кастомного скрипта для переименования компонента OldButton в Button:

export default function transformer(file, api) {
  const j = api.jscodeshift;
  const root = j(file.source);

  root.find(j.ImportDeclaration, { source: { value: 'antd' } })
    .find(j.ImportSpecifier)
    .forEach(path => {
      if (path.node.imported.name === 'OldButton') {
        path.node.imported.name = 'Button';
      }
    });

  return root.toSource();
}

Такой подход позволяет обрабатывать любые пользовательские кейсы миграции, которые не покрыты стандартными пакетами Ant Design.

Практические рекомендации

  • Всегда использовать git или другую систему контроля версий перед запуском codemod. Это обеспечивает возможность отката в случае некорректных изменений.
  • Прогонять codemod на тестовом бранче. Даже проверенные скрипты могут не учесть кастомные расширения компонентов.
  • Проверять результаты линтером и unit-тестами. Codemod выполняет изменения на уровне синтаксиса, но логика работы компонентов может требовать дополнительной проверки.
  • Разделять миграцию на этапы — сначала обновление структуры компонентов, затем переименование свойств и удаление deprecated API. Это упрощает поиск и исправление возможных проблем.

Интеграция с CI/CD

Для крупных проектов полезно интегрировать codemod в pipeline CI/CD, чтобы автоматизировать миграцию при обновлении зависимости Ant Design. Это позволяет:

  • Сразу проверять совместимость с новой версией;
  • Минимизировать ручной труд разработчиков;
  • Поддерживать кодовую базу актуальной без больших рисков.

Пример команды в CI:

npx @ant-design/codemod v4-to-v5 ./src --dry
npm test

Такой подход позволяет сначала выполнить тестовый прогон, затем применить изменения только после успешного прохождения тестов.

Поддерживаемые версии и обновления

Codemod для Ant Design выпускается синхронно с релизами библиотеки. Основные сценарии:

  • v3 → v4: переименование компонентов и атрибутов, обновление стилей и тем;
  • v4 → v5: новые API для Form, Table, Button, изменения в Grid и Typography.

Использование codemod ускоряет процесс миграции и снижает риск ошибок при переходе между крупными версиями.

Оглавление