# Migrate from v4

First, install the latest Vue CLI globally:

npm install -g @vue/cli@next
# OR
yarn global add @vue/cli@next

# Upgrade All Plugins at Once

In your existing projects, run:

vue upgrade --next

And then follow the command line instructions.

See the following section for detailed breaking changes introduced in each package.

Note

If you see errors like setup compilation vue-loader-plugin(node:44156) UnhandledPromiseRejectionWarning: TypeError: The 'compilation' argument must be an instance of Compilation after upgrading, please remove the lockfile (yarn.lock or package-lock.json) and node_modules in the project and reinstall all the dependencies.


# One-By-One Manual Migration

If you want to migrate manually and gradually, you can run vue upgrade <the-plugin-name> to upgrade a specific Vue CLI plugin.


# Breaking Changes

# For All Packages

  • Drop support of Node.js 8-11 and 13
  • Drop support of NPM 5

# The vue Command (The Global @vue/cli Package)

The instant prototyping functionalities (opens new window) are removed. Now the vue serve / vue build commands are aliases to npm run serve / npm run build, which in turn execute the scripts specified in the project package.json.

If you need a minimum setup for developing standalone .vue components, please use vite (opens new window) instead.

# @vue/cli-service

# Webpack 5

We've upgraded the underlying webpack version to 5. There are plenty of breaking changes underlyingly, listed in the release announcement page Webpack 5 release (2020-10-10) (opens new window).

Besides the internal changes that are only noticeable for custom configurations, there're several notable changes for user-land code too:

  1. Named exports from JSON modules are no longer supported. Instead of import { version } from './package.json'; console.log(version); use import package from './package.json'; console.log(package.version);
  2. Webpack 5 does no longer include polyfills for Node.js modules by default. You shall see an informative error message if your code relies on any of these modules. A detailed list of previously polyfilled modules is also available here (opens new window).

# Opt Out to Webpack 4

Considering many ecosystem packages haven't catched up yet, we provided a plugin to opt out to webpack 4 for easier migration.

It's as simple as running

vue add webpack-4

at the project root.

Underlyingly, it uses the resolutions (opens new window) field for Yarn and PNPM users, and module-alias (opens new window) for NPM users.

Though both work in all our tests, please be aware that the module-alias approach is still considered hacky, and may not be as stable as the "resolutions" one.

# Changes to the build command and modern mode

Starting with v5.0.0-beta.0, running vue-cli-service build will automatically generate different bundles based on your browserslist configurations. The --modern flag is no longer needed because it is turned on by default.

Say we are building a simple single-page app with the default setup, here are some possible scenarios:

  • With the default browserslist target of Vue 2 projects (> 1%, last 2 versions, not dead), vue-cli-service build will produce two types of bundles:
    • One for modern target browsers that support <script type="module"> (app.[contenthash].js and chunk-vendors.[contenthash].js). The bundle size will be much smaller because it drops polyfills and transformations for legacy browsers.
    • One for those do not (app-legacy.[contenthash].js and chunk-vendors-legacy.[contenthash].js), and will be loaded via <script nomodule>.
  • You can opt-out this behavior by appending a --no-module flag to the build command. vue-cli-service build --no-module will only output the legacy bundles that support all target browsers (loaded via plain <script>s).
  • With the default browserslist target of Vue 3 projects (> 1%, last 2 versions, not dead, not ie 11), all target browsers supports <script type="module">, there's no point (and no way) differentiating them, thus vue-cli-service build will only produce one type of bundle: app.[contenthash].js and chunk-vendors.[contenthash].js (loaded via plain <script>s).

# CSS Modules

The css.requireModuleExtension option is removed. If you do need to strip the .module part in CSS Module file names, please refer to Working with CSS > CSS Modules for more guidance.

css-loader is upgraded from v3 to v5, a few CSS Module related options have been renamed, along with other changes. See full changelog (opens new window) for additional details.

# Sass/SCSS

No longer supports generating project with node-sass. It has been deprecated (opens new window) for a while. Please use the sass package instead.

# Underlying Loaders and Plugins

# Babel Plugin

The transpileDependencies option now accepts a boolean value. Setting it to true will transpile all dependencies inside node_modules.

# ESLint Plugin

# PWA Plugin

# TypeScript Plugin

# E2E-Cypress Plugin

# E2E-WebDriverIO Plugin

# Unit-Jest Plugin

  • For Vue 2 projects, vue-jest is now required as a peer dependency, please install vue-jest@^4.0.1 as a dev dependency to the project.
  • For TypeScript projects, ts-jest is now required as a peer dependency. Users need to install ts-jest@26 manually to the project root.
  • The underlying jest-related packages are upgraded from v24 to v26. For most users the transition would be seamless. See their corresponding changelogs for more detail:

# Unit-Mocha Plugin

# Internal Packages

# @vue/cli-shared-utils