ContextQMD
Back to Vue Cli

Migrate from v4

docs/migrations/migrate-from-v4.md

5.0.912.0 KB
Original Source

Migrate from v4

First, install the latest Vue CLI globally:

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

Upgrade All Plugins at Once

In your existing projects, run:

bash
vue upgrade

And then follow the command line instructions.

Note that the migrator is not complete yet and doesn't cover all cases. Please read the following section for detailed breaking changes introduced in each package.

::: tip 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 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 https://sfc.vuejs.org/ or https://vite.new/vue 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).

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.

Dev Server

webpack-dev-server has been updated from v3 to v4. So there are breaking changes with regard to the devServer option in vue.config.js. Please check out the webpack-dev-server migration guide for more details.

Most notably:

  • The disableHostCheck option was removed in favor allowedHosts: 'all';
  • public, sockHost, sockPath, and sockPort options were removed in favor client.webSocketURL option.
  • IE9 support of the dev server is not enabled by default. If you need to develop under IE9, please manually set the devServer.webSocketServer option to sockjs.

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 v6, a few CSS Module related options have been renamed, along with other changes. See full changelog for additional details.

Sass/SCSS

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

Asset Modules

url-loader and file-loader are removed in favor of Asset Modules. If you want to adjust the size limit of inline image assets, now you need to set the Rule.parser.dataUrlCondition.maxSize option:

js
// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('images')
        .set('parser', {
          dataUrlCondition: {
            maxSize: 4 * 1024 // 4KiB
          }
        })
  }
}

Underlying Loaders and Plugins

  • html-webpack-plugin is upgraded from v3 to v5. More details are available in the release announcement of html-webpack-plugin v4 and the full changelog.
  • sass-loader v7 support is dropped. See the v8 breaking changes at its changelog.
  • postcss-loader is upgraded from v3 to v5. Most notably, PostCSS options (plugin / syntax / parser / stringifier) are moved into the postcssOptions field. More details available at the changelog.
  • copy-webpack-plugin is upgraded from v5 to v8. If you never customized its config through config.plugin('copy'), there should be no user-facing breaking changes. A full list of breaking changes is available at copy-webpack-plugin v6.0.0 changelog.
  • terser-webpack-plugin is upgraded from v2 to v5, using terser 5 and some there are some changes in the options format. See full details in its changelog.
  • When creating new projects, the default less-loader is updated from v5 to v8; less from v3 to v4; sass-loader from v8 to v11; stylus-loader from v3 to v5.
  • mini-css-extract-plugin is upgraded from v1 to v2.
  • cache-loader is removed. If you want to use it, please install it manually.

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

  • Dropped TSLint support. As TSLint has been deprecated, we removed all TSLint-related code in this version. Please consider switching to ESLint. You can check out tslint-to-eslint-config for a mostly automatic migration experience.
  • ts-loader is upgraded from v6 to v9. It now only supports TypeScript >= 3.6.
  • fork-ts-checker-webpack-plugin is upgraded from v3.x to v6.x, you can see the detailed breaking changes in its release notes:

E2E-Cypress Plugin

  • Cypress is required as a peer dependency.
  • Cypress is updated from v3 to v8. See Cypress Migration Guide for detailed instructions of the migration process.

E2E-WebDriverIO Plugin

  • WebDriverIO is updated from v6 to v7. Not many user-facing breaking changes. See the blog post on release for more details.

E2E-Nightwatch Plugin

Unit-Jest Plugin

  • For Vue 2 projects, @vue/vue2-jest is now required as a peer dependency, please install @vue/vue2-jest 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@27 manually to the project root.
  • The underlying jest-related packages are upgraded from v24 to v27. For most users the transition would be seamless. See their corresponding changelogs for more detail:

Unit-Mocha Plugin

Internal Packages

@vue/cli-shared-utils

  • chalk is upgraded from v2 to v4
  • joi is upgraded from v15 (used to be @hapi/joi) to v17