Skip to content

Latest commit

 

History

History
148 lines (94 loc) · 10.4 KB

migrate-from-v4.md

File metadata and controls

148 lines (94 loc) · 10.4 KB
sidebar
auto

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.

::: 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.

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 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.

Underlying Loaders and Plugins

  • html-webpack-plugin is upgraded from v3 to v5, and for webpack 4 users, v4 will be used. 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 (v4 for webpack 4 users). 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 (v6 if you choose to stay at webpack 4). 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.
  • file-loader is upgraded from v4 to v6, and url-loader from v2 to v4. The esModule option is now turned on by default for non-Vue-2 projects. Full changelog available at file-loader changelog and url-loader changelog.
  • terser-webpack-plugin is upgraded from v2 to v5 (v4 if you choose to stay at webpack 4), 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(v7 for webpack 4 users); less from v3 to v4; sass-loader from v8 to v11 (v10 for webpack 4 users); stylus-loader from v3 to v5 (v4 for webpack 4 users).

Babel Plugin

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

ESLint Plugin

  • eslint-loader is replaced by eslint-webpack-plugin, dropping support for ESLint <= 6.
  • New projects are now generated with eslint-plugin-vue v7, see its release notes for breaking changes.

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 v8. 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 v7. 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.

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

  • mocha is upgraded from v6 to v8, please refer to the release notes of mocha v7 and mocha v8 for a complete list of breaking changes.
  • jsdom is upgraded from v15 to v16, the breaking changes are listed at jsdom v16.0.0 release

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