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

Развитие библиотеки интерфейсных компонентов сопровождается изменениями API, структуры компонентов, подходов к стилизации и конфигурации. При переходе между крупными версиями библиотеки требуется адаптация существующего кода. В экосистеме Vuetify для этого используются специальные инструменты миграции, которые автоматизируют преобразование проектов и уменьшают объём ручной работы.

Инструменты миграции решают несколько задач:

  • анализ существующего кода проекта;
  • автоматическое обновление синтаксиса компонентов;
  • преобразование устаревших API;
  • адаптация конфигурационных файлов;
  • обновление структуры импорта;
  • помощь в переходе на новые механизмы стилизации и темизации.

Использование таких инструментов особенно важно при переходе между крупными версиями, например с Vuetify 2 на Vuetify 3, где были изменены многие внутренние механизмы.

Основные сценарии миграции

Процесс миграции обычно включает несколько этапов:

  1. Обновление зависимостей
  2. Преобразование исходного кода
  3. Адаптация конфигурации
  4. Исправление несовместимостей
  5. Тестирование и доработка

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

Vuetify Migration Helper

Один из основных инструментов — утилита миграции, предназначенная для анализа проекта и предложения изменений. Она выполняет:

  • поиск устаревших компонентов
  • обнаружение удалённых API
  • проверку структуры импорта
  • выявление несовместимых параметров

Типичная проверка выполняется после обновления зависимостей.

Пример обновления зависимостей

npm install vuetify@latest

или

yarn add vuetify@latest

После обновления выполняется анализ проекта.

Автоматические код-модификаторы (Codemods)

Codemods — это скрипты, автоматически преобразующие исходный код проекта. Они основаны на анализе AST (Abstract Syntax Tree) и позволяют безопасно изменять структуру кода.

Такие инструменты выполняют следующие операции:

  • переименование компонентов
  • обновление свойств
  • изменение синтаксиса слотов
  • обновление импорта

Пример изменения импорта

Vuetify 2:

import Vuetify from 'vuetify'

Vue.use(Vuetify)

Vuetify 3:

import { createVuetify } from 'vuetify'

const vuetify = createVuetify()

Codemods автоматически заменяют подобные конструкции во всём проекте.

Миграция компонентов

Во время перехода между версиями многие компоненты были переработаны. Некоторые из них:

  • получили новые свойства
  • изменили структуру слотов
  • были объединены или разделены
  • были удалены

Инструменты миграции помогают обнаружить такие изменения.

Пример изменения компонента кнопки

Vuetify 2:

<v-btn color="primary" dark>
  Submit
</v-btn>

Vuetify 3:

<v-btn color="primary" variant="flat">
  Submit
</v-btn>

Параметр dark больше не используется, так как система темизации изменилась.

Изменения в системе тем

Vuetify 3 полностью переработал механизм темизации. Вместо старых параметров используется централизованная конфигурация.

Vuetify 2:

new Vuetify({
  theme: {
    dark: true
  }
})

Vuetify 3:

createVuetify({
  theme: {
    defaultTheme: 'dark'
  }
})

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

Миграция системы сетки

Сетка также получила изменения. Хотя базовые компоненты (v-container, v-row, v-col) остались, некоторые параметры изменились.

Инструменты миграции проверяют:

  • устаревшие атрибуты
  • удалённые классы
  • несовместимые параметры

Пример старого синтаксиса:

<v-layout row>
  <v-flex xs12>
    Content
  </v-flex>
</v-layout>

Новый синтаксис:

<v-row>
  <v-col cols="12">
    Content
  </v-col>
</v-row>

Codemods могут автоматически преобразовать такие структуры.

Миграция иконок

В Vuetify 3 изменился механизм подключения иконок. Теперь используется централизованная система и провайдеры.

Старая конфигурация:

new Vuetify({
  icons: {
    iconfont: 'mdi'
  }
})

Новая конфигурация:

createVuetify({
  icons: {
    defaultSet: 'mdi'
  }
})

Инструменты миграции могут обнаружить старые настройки и обновить их.

Обновление слотов

Система слотов также была изменена. В Vuetify 3 используются возможности Vue 3, включая улучшенные scoped slots.

Старый синтаксис:

<template slot="activator" slot-scope="{ on }">
  <v-btn v-on="on">Open</v-btn>
</template>

Новый синтаксис:

<template #activator="{ props }">
  <v-btn v-bind="props">Open</v-btn>
</template>

Codemods автоматически обновляют большинство таких конструкций.

Миграция конфигурации плагина

Vuetify 3 использует другой механизм инициализации.

Vuetify 2:

import Vue from 'vue'
import Vuetify from 'vuetify'

Vue.use(Vuetify)

export default new Vuetify()

Vuetify 3:

import { createVuetify } from 'vuetify'

export const vuetify = createVuetify()

Также изменяется способ подключения в приложении:

createApp(App)
  .use(vuetify)
  .mount('#app')

Миграция системы стилей

Vuetify 3 использует новый механизм работы со стилями на основе CSS Variables.

Инструменты миграции помогают обнаружить:

  • устаревшие Sass-переменные
  • удалённые классы
  • несовместимые стили

Старый подход:

$btn-border-radius: 8px;

Новый подход основан на CSS-переменных и настройках темы.

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

После автоматической миграции рекомендуется проверить:

  • пользовательские компоненты
  • кастомные директивы
  • плагины
  • сторонние библиотеки

Некоторые библиотеки могут поддерживать только старую версию Vuetify.

Типичная проверка выполняется через запуск проекта:

npm run dev

или

yarn dev

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

Использование ESLint для обнаружения устаревшего кода

Дополнительным инструментом может выступать ESLint с правилами, выявляющими устаревшие конструкции.

Такие правила помогают:

  • обнаружить deprecated API
  • предупредить использование старых компонентов
  • обеспечить единый стиль кода после миграции

Пример проверки:

npx eslint src

Миграция TypeScript-проектов

В проектах с TypeScript могут потребоваться дополнительные изменения:

  • обновление типов
  • изменение импортов
  • адаптация интерфейсов компонентов

Vuetify 3 предоставляет новые типы для компонентов и конфигурации.

Пример импорта типов:

import { createVuetify } from 'vuetify'
import type { ThemeDefinition } from 'vuetify'

Инструменты миграции могут обновлять часть таких импортов автоматически.

Ручная корректировка после автоматической миграции

Даже после применения codemods остаются участки, требующие ручной доработки:

  • сложные слоты
  • динамическая генерация компонентов
  • кастомные темы
  • собственные плагины

Поэтому автоматическая миграция рассматривается как подготовительный этап, значительно сокращающий объём работы, но не полностью заменяющий ручной аудит кода.

Типичная стратегия безопасной миграции

На практике используется поэтапный подход:

  1. создание отдельной ветки проекта
  2. обновление зависимостей
  3. запуск инструментов миграции
  4. применение codemods
  5. исправление ошибок сборки
  6. тестирование интерфейса
  7. обновление документации проекта

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

Оглавление