⚠️ Vue CLI is in Maintenance Mode!

For new projects, it is now recommended to use create-vue to scaffold Vite-based projects. Also refer to the Vue 3 Tooling Guide for the latest recommendations.

Миграция с версии v3

Для начала глобально установите последнюю версию Vue CLI:

npm install -g @vue/cli
# ИЛИ
yarn global add @vue/cli

Обновление всех плагинов сразу

В существующих проектах запустите команду:

vue upgrade

После чего ознакомьтесь со следующим разделом с информацией о крупных изменениях (breaking changes) в каждом пакете.


Миграция вручную по одному пакету

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

Глобальный пакет @vue/cli

Переработана команда vue upgrade

  • Было: vue upgrade [patch | minor | major] — выполняла только установку последних версий плагинов Vue CLI.
  • Стало: vue upgrade [plugin-name] — кроме обновления плагинов, запускает миграции из них для автоматизации процесса обновления. Для получения информации о дополнительных опциях этой команды выполните vue upgrade --help.

Изменён формат вывода vue --version

При запуске vue --version:

  • 3.x: выводит 3.12.0
  • 4.x: выводит @vue/cli 4.0.0

Добавлен дополнительный шаг подтверждения во избежание перезаписи

При запуске vue invoke / vue add / vue upgrade теперь появляется дополнительный шаг подтверждения при наличии незафиксированных изменений в текущем репозитории.

image

Vue Router и Vuex теперь имеют сопутствующие CLI-плагины

При запуске vue add vuex или vue add router:

  • В версии 3, только vuex или vue-router добавляется в проект;
  • В версии 4, также устанавливается @vue/cli-plugin-vuex или @vue/cli-plugin-router.

В настоящее время это не привносит ничего особенного для конечных пользователей, но такой подход позволяет добавлять больше возможностей для пользователей Vuex и Vue Router позднее.

Для разработчиков пресетов и плагинов есть ещё несколько изменений в этих двух плагинах:

  • Структура каталогов по умолчанию изменена:
    • src/store.js перемещён в src/store/index.js;
    • src/router.js перемещён в src/router/index.js;
  • Опции router и routerHistoryMode в файле preset.json по-прежнему поддерживаются для совместимости. Но рекомендуется использовать plugins: { '@vue/cli-plugin-router': { historyMode: true } } для консистентности.
  • api.hasPlugin('vue-router') больше не поддерживается. Теперь api.hasPlugin('router').

@vue/cli-service

Обработка пробелов в шаблонах

Во Vue CLI v3 для уменьшения размеров итоговой сборки по умолчанию отключена опция preserveWhitespace для vue-template-compiler.

Однако это привносило свои тонкости использования.

Но после релиза Vue 2.6 теперь можно управлять обработкой пробелов с помощью новой опции whitespace. Поэтому во Vue CLI v4 перешли на использование этой новой опции по умолчанию.

Возьмём в качестве примера следующий шаблон:

<p>
  Welcome to <b>Vue.js</b> <i>world</i>.
  Have fun!
</p>

С опцией preserveWhitespace: false все пробелы между тегами будут удалены, поэтому он скомпилируется в:

<p> Welcome to <b>Vue.js</b><i>world</i>. Have fun! </p>

С опцией whitespace: 'condense' он скомпилируется в:

<p> Welcome to <b>Vue.js</b> <i>world</i>. Have fun! </p>

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

vue-cli-service build --mode development

Раньше при запуске команды build в режиме development расположение каталога dist отличалось от расположения в режиме production. Теперь, с учётом указанных ниже двух пулл-реквестов, структура и расположение каталогов будет во всех режимах одинакова (имена файлов всё ещё различаются — никаких хэшей в режиме development):

  • #4323 ensure consistent directory structure for all modes
  • #4302 move dev configs into serve command

Для пользователей SASS/SCSS

Раньше во Vue CLI v3 использовался sass-loader@7 по умолчанию.

Недавно вышел sass-loader@8 в котором довольно сильно изменился формат конфигурации. Примечания к релизу: https://github.com/webpack-contrib/sass-loader/releases/tag/v8.0.0

@vue/cli-service продолжает поддерживать sass-loader@7 в v4, но настоятельно рекомендуем обратить внимание на релиз sass-loader@8 и обновиться до последней версии.

Для пользователей Less

less-loader v4 несовместим с less >= v3.10, см. https://github.com/less/less.js/issues/3414. Настоятельно рекомендуем обновиться до less-loader@5, если в проекте используется Less.

Для пользователей CSS модулей

Настройки vue.config.js

Уже объявленная как устаревшая опция baseUrl теперь удалена.

chainWebpack / configureWebpack

Метод minimizer в chainWebpack

Если настраивали правила через chainWebpack, то обратите внимание, что webpack-chain обновлён с версии v4 до v6. Наиболее заметным изменением является конфигурация minimizer.

Например, если необходимо включить опцию drop_console в плагине terser. В версии v3 это можно сделать через chainWebpack так:

const TerserPlugin = require('terser-webpack-plugin')
module.exports = {
  chainWebpack: (config) => {
    config.optimization.minimizer([
      new TerserPlugin({ terserOptions: { compress: { drop_console: true } } })
    ])
  }
}

В версии v4 необходимо изменить таким образом:

module.exports = {
  chainWebpack: (config) => {
    config.optimization.minimizer('terser').tap((args) => {
      args[0].terserOptions.compress.drop_console = true
      return args
    })
  }
}
Другие изменения

Базовые загрузчики / плагины

Скорее всего это вряд ли повлияет на пользователей, если не настраивали опции через chainWebpack / configureWebpack

css-loader был обновлён с версии v1 до v3:

Несколько базовых загрузчиков и плагинов webpack обновлены, с незначительными изменениями:

@vue/cli-plugin-babel, @vue/babel-preset-app

core-js

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

Во Vue CLI v3 использовалась core-js версии 2.x, теперь она обновлена до 3.x.

Эта миграция автоматизирована, достаточно выполнить команду vue upgrade babel. Но если добавлялись пользовательские полифилы, может потребоваться обновить имена полифилов (подробную информацию можно найти в истории изменений core-js).

Пресет Babel

Эта миграция также автоматизирована, при обновлении командой vue upgrade babel.

  • В версии v3, babel пресет по умолчанию в babel.config.js был @vue/app.
  • В версии v4, пресет перемещён в плагин и теперь называется @vue/cli-plugin-babel/preset

Необходимость этого в том, что @vue/babel-preset-app в действительности является косвенной зависимостью проекта. Это работает благодаря «поднятию» (hoisting) npm-пакета. Однако может стать причиной потенциальных проблем, если у проекта несколько косвенных зависимостей одного и того же пакета, или если менеджер пакетов накладывает более строгие ограничения при разрешении зависимостей (например, yarn plug'n'play или pnpm). Поэтому он вынесен отдельной зависимостью проекта (@vue/cli-plugin-babel) для большей совместимости со стандартами и меньшей подверженности ошибкам.


@vue/cli-plugin-eslint

Плагин теперь требует ESLint в качестве peer-зависимости.

Это не повлияет на проекты, созданные с помощью Vue CLI 3.1 или более поздних версий.

Если проект был создан с помощью Vue CLI 3.0.x или более ранних версий, то потребуется добавить eslint@4 к зависимостям проекта (это автоматизированно при обновлении плагина с помощью команды vue upgrade eslint).

Также рекомендуется обновить ESLint до версии v5, а конфигурацию ESLint до последней версии (поддержка ESLint v6 будет добавлена в ближайшем будущем).


Пресет Prettier

Старая реализация пресета prettier была несовершенной. Шаблон по умолчанию обновлён с версии Vue CLI v3.10.

Теперь требуются eslint, eslint-plugin-prettier и prettier в качестве peer-зависимостей, следуя стандартным практикам экосистемы ESLint.

В старых проектах при возникновении проблем как Cannot find module: eslint-plugin-prettier необходимо выполнить следующую команду для их исправления:

npm install --save-dev eslint@5 @vue/eslint-config-prettier@5 eslint-plugin-prettier prettier

Настройки lintOnSave

(затрагивает только процесс разработки)

Значение по умолчанию для опции lintOnSave (если не было указано) изменено с true на 'default'. Ознакомиться с подробным объяснением можно в документации.

Вкратце:

  • В версии v3, по умолчанию, предупреждения линтинга и ошибки отображаются в браузере в слое для ошибок поверх приложения.
  • В версии v4, по умолчанию, только ошибки линтинга будут таким образом прерывать процесс разработки. Предупреждения будут отображаться в консоли терминала.

@vue/cli-plugin-pwa

Базовый плагин workbox-webpack-plugin обновлён с версии v3 до v4. См. примечания к релизу.

Теперь доступно поле pwa.manifestOptions (его можно указать в файле vue.config.js). Благодаря этой опции можно сгенерировать manifest.json из объекта конфигурации, а не копировать из каталога public. Это обеспечивает более консистентный интерфейс управления конфигурацией PWA (Обратите внимание, что это опциональная возможность. Связанные пулл-реквесты: #2981, #4664).

@vue/cli-plugin-e2e-cypress

До Vue CLI v3.0.0-beta.10 команда для E2E-тестирования по умолчанию была vue-cli-service e2e. Позднее изменена на vue-cli-service test:e2e. Предыдущая команда объявлена устаревшей, но всё ещё поддерживалась. Теперь поддержка старой команды удалена.

@vue/cli-plugin-e2e-nightwatch

Nightwatch.js обновлён с версии 0.9 до 1.x. Рекомендуем сначала изучить руководство по миграции Nightwatch.

Поставляемая в комплекте конфигурация и генерируемые тесты были полностью переработаны. Перейдите по ссылке для получения более подробной информации. Большинство используемых кейсов во Vue CLI v3 по-прежнему поддерживаются. Это просто добавление новых возможностей.

Поскольку ChromeDriver изменил свою стратегию версионирования с 73-й версии, теперь он сделан peer-зависимостью проекта. В плагине реализована простая проверка версии браузера, поэтому при обновлении до несовместимой версии Chrome появится предупреждение с предложением обновить до соответствующей версии и ChromeDriver.


Аналогично плагину для cypress, поддержка устаревшей команды vue-cli-service e2e удалена.

@vue/cli-plugin-typescript

При импорте файла без расширения, настройки webpack по разрешению модулей теперь отдают предпочтение файлам с расширениями ts(x) вместо js(x) и .vue. Настоятельно рекомендуется всегда указывать расширение файла при импорте .vue файлов.

@vue/cli-plugin-unit-jest

Обновлён Jest с версии v23 до v24, поэтому рекомендуем сначала изучить примечания к релизу. А также, при необходимости, ознакомиться с полной историей изменений.

Плагин unit-jest теперь поставляется с 4 пресетами конфигурации:

  • @vue/cli-plugin-unit-jest — пресет по умолчанию для наиболее распространённых типов проектов
  • @vue/cli-plugin-unit-jest/presets/no-babel — если не установлен @vue/cli-plugin-babel и требуется не использовать babel в проекте
  • @vue/cli-plugin-unit-jest/presets/typescript — пресет с поддержкой TypeScript (но без поддержки TSX)
  • @vue/cli-plugin-unit-jest/presets/typescript-and-babel — пресет с поддержкой TypeScript (в том числе TSX) и babel.

Если после создания проекта стандартная конфигурация Jest не изменялась (расположена в файле jest.config.js или в поле jest в package.json), то можно просто заменить массивный объект конфигурации одним единственным полем:

module.exports = {
  // Замените имя пресета на одно из списка выше по необходимости
  preset: '@vue/cli-plugin-unit-jest'
}

(зависимости ts-jest, babel-jest можно удалить после миграции конфигурации на использование пресета)

Напоминание

По умолчанию тестовое окружение в новых пресетах использует jsdom@15, что отличается от среды по умолчанию в Jest 24 (jsdom@11). Это должно быть согласовано в предстоящем обновлении Jest 25. Большинство пользователей не будут затронуты этим изменением. Подробную информацию, связанную с jsdom, можно найти в истории изменений https://github.com/jsdom/jsdom/blob/master/Changelog.md

@vue/cli-plugin-unit-mocha

@vue/cli-service-global

См. подробные изменения в пакетах @vue/cli-service и @vue/cli-plugin-eslint.