sidebar |
---|
auto |
First, install the latest Vue CLI globally:
npm install -g @vue/cli@next
# OR
yarn global add @vue/cli@next
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.
:::
If you want to migrate manually and gradually, you can run vue upgrade <the-plugin-name>
to upgrade a specific Vue CLI plugin.
- Drop support of Node.js 8-11 and 13
- Drop support of NPM 5
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.
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:
- Named exports from JSON modules are no longer supported. Instead of
import { version } from './package.json'; console.log(version);
useimport package from './package.json'; console.log(package.version);
- 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.
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 favorallowedHosts: 'all'
; public
,sockHost
,sockPath
, andsockPort
options were removed in favorclient.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 tosockjs
.
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
andchunk-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
andchunk-vendors-legacy.[contenthash].js
), and will be loaded via<script nomodule>
.
- One for modern target browsers that support
- 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, thusvue-cli-service build
will only produce one type of bundle:app.[contenthash].js
andchunk-vendors.[contenthash].js
(loaded via plain<script>
s).
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.
No longer supports generating project with node-sass
. It has been deprecated for a while. Please use the sass
package instead.
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:
// vue.config.js
module.exports = {
chainWebpack: config => {
config.module
.rule('images')
.set('parser', {
dataUrlCondition: {
maxSize: 4 * 1024 // 4KiB
}
})
}
}
html-webpack-plugin
is upgraded from v3 to v5. More details are available in the release announcement ofhtml-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 thepostcssOptions
field. More details available at the changelog.copy-webpack-plugin
is upgraded from v5 to v8. If you never customized its config throughconfig.plugin('copy')
, there should be no user-facing breaking changes. A full list of breaking changes is available atcopy-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.
The transpileDependencies
option now accepts a boolean value. Setting it to true
will transpile all dependencies inside node_modules
.
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.
- The underlying
workbox-webpack-plugin
is upgraded from v4 to v6. Detailed migration guides available on workbox's website:
- 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:
- 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.
- WebDriverIO is updated from v6 to v7. Not many user-facing breaking changes. See the blog post on release for more details.
- 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 installts-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:
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 v17, user-facing breaking changes are listed in thejsdom
v16.0.0 release notes.