From a0bd56866ac9ef8d431bf159602df6caffbdd1cd Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 8 Sep 2019 13:35:05 +0800 Subject: [PATCH 01/27] docs: [wip] migration guide from v3 to v4 --- docs/.vuepress/config.js | 7 +- docs/guide/migrating-from-v3.md | 130 ++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 docs/guide/migrating-from-v3.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b0c6d276ed..3a256b67bf 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -85,6 +85,10 @@ module.exports = { text: 'Plugins', link: '/core-plugins/' }, + { + text: 'Migrating From v3', + link: '/guide/migrating-from-v3' + }, { text: 'Changelog', link: 'https://github.com/vuejs/vue-cli/blob/dev/CHANGELOG.md' @@ -115,7 +119,8 @@ module.exports = { '/guide/mode-and-env', '/guide/build-targets', '/guide/deployment', - '/guide/troubleshooting' + '/guide/troubleshooting', + '/guide/migrating-from-v3' ] } ], diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md new file mode 100644 index 0000000000..d1c99e72e6 --- /dev/null +++ b/docs/guide/migrating-from-v3.md @@ -0,0 +1,130 @@ +# Migration from v3 + +First, install the latest Vue CLI globally: +``` +npm install -g @vue/cli@4 +``` + +## Auto Migration + +In your existing projects, run: +``` +vue upgrade --all --next +``` + +Please refer to the [Breaking Changes](#breaking-changes) section for all the possible breaking changes introduced. + +------ + +## Manual Migration + +If you want to do the migration manually and gradually, here are the tips: + +### The Global `@vue/cli` Package + +The `vue upgrade` command was [redesigned](https://github.com/vuejs/vue-cli/pull/4090). +- Before: `vue upgrade [patch | minor | major]`, and it does nothing more than install the latest versions of Vue CLI plugins. +- After: `vue upgrade [plugin-name]`. Aside from upgrading the plugins, it can run migrators from plugins to help you automate the migration process. For more options for this command, please run `vue upgrade --help`. + +--- + +When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra confirmation step](https://github.com/vuejs/vue-cli/pull/4275) if you have uncommitted changes in the current repository. + +--- + +When running `vue add vuex` or `vue add router`: +- in v3, only `vuex` or `vue-router` will be added to the project; +- in v4, there will also be `@vue/cli-plugin-vuex` & `@vue/cli-plugin-router` installed. + +This currently does not make an actual difference for end users, but such design allows us to add more features for vuex & vue-router users later. + +### `@vue/cli-service` + +* [#4323](https://github.com/vuejs/vue-cli/pull/4323) ensure consistent directory structure for all modes + +* [#4302](https://github.com/vuejs/vue-cli/pull/4302) move dev configs into serve command + +* [TODO: notes on less-loader version] + + +#### `vue.config.js` + +* The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) + +* [deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. + +* [Upgraded versions of several underlying webpack loaders](https://github.com/vuejs/vue-cli/pull/4331) [TODO elaborate this] + +If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. [TODO: add example here]. + +Please also notice that the following rules/loaders have been updated: + +1. [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20), the `debug` option was renamed to `logLevel` +2. [use EnvironmentPlugin instead of DefinePlugin for `process.env.*` vars](https://github.com/vuejs/vue-cli/pull/3782), [TODO: detailed explanation] +3. [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) + +### `@vue/babel-preset-app`, `@vue/cli-plugin-babel` + +- [Upgrade to core-js v3](https://github.com/vuejs/vue-cli/pull/3912). [TODO: detailed explanation] +- Use `@vue/cli-plugin-babel/preset` [TODO: auto migration & elaborate on this] + +------ + +### `@vue/cli-plugin-eslint` + +This plugin now [requires ESLint as a peer dependency]((https://github.com/vuejs/vue-cli/pull/3852)). + +This won't affect projects scaffolded with Vue CLI 3.1 or later. + +If your project was scaffolded with Vue CLI 3.0.x or earlier, you may need to add `eslint@4` to your project dependencies (This is automated if you upgrade the plugin using `vue upgrade eslint --next`). + +It's also recommended to upgrade your ESLint to v5, and ESLint config versions to latest. (ESLint v6 support is still on the way) + +--- + +[TODO][Notes on prettier config] + +--- + +(the following only affects development) + +The default value of `lintOnSave` option (when not specified) was [changed from `true` to `'default'`](https://github.com/vuejs/vue-cli/pull/3975). You can read more on the detailed explanation in the [documentation](https://cli.vuejs.org/config/#lintonsave). + +In a nutshell: +- In v3, by default, lint warnings, along with errors, will be displayed in the error overlay +- In v4, by default, only lint errors will interrupt your development process. Warnings are only logged in the terminal console. + +### `@vue/cli-plugin-pwa` + +* [Upgraded to workbox v4](https://github.com/vuejs/vue-cli/pull/3915) +* [`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) + +### `@vue/cli-plugin-e2e-cypress` + +Before Vue CLI v3.0.0-beta.10, the default command for E2E testing was `vue-cli-service e2e`. Later we changed it to `vue-cli-service test:e2e`. The previous command was since deprecated but still supported. +We have now completely [dropped support for this legacy command](https://github.com/vuejs/vue-cli/pull/3774). + +### `@vue/cli-plugin-e2e-nightwatch` + +* [#3388](https://github.com/vuejs/vue-cli/pull/3388) upgrade to nightwatch v1 +* [#3916](https://github.com/vuejs/vue-cli/pull/3916) upgrade to chromedriver v74 and make it a peer dependency +* [#3774](https://github.com/vuejs/vue-cli/pull/3774) remove support for legacy `vue-cli-service e2e` command + +### `@vue/cli-plugin-typescript` + +When using Typescript, the webpack resolve options now [prefer `ts(x)` file extensions over `js(x)` ones](https://github.com/vuejs/vue-cli/pull/3909). + +### `@vue/cli-plugin-unit-jest` + +* [Upgraded to jest v24](https://github.com/vuejs/vue-cli/pull/3870) + +[TODO: More detailed information to be added…] + +### `@vue/cli-plugin-unit-mocha` + +* Use mochapack instead of mocha-webpack, see changelog at . This change is not likely to affect actual usage. +* Upgraded to mocha 6, see + +### `@vue/cli-service-global` + +See breaking changes in the [`@vue/cli-service`](#vue-cli-service) & [`@vue/cli-plugin-eslint`](#vue-cli-plugin-eslint) packages. From b8ad3d74721ffdb75e1218fc5c06323486fc5b49 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 8 Sep 2019 13:48:33 +0800 Subject: [PATCH 02/27] docs: migration -> migrating --- docs/guide/migrating-from-v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index d1c99e72e6..f337f4c5ce 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -1,4 +1,4 @@ -# Migration from v3 +# Migrating from v3 First, install the latest Vue CLI globally: ``` From 8e91c02d9c777c77cf602e37e3df4d0b118e3e09 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 8 Sep 2019 13:48:52 +0800 Subject: [PATCH 03/27] docs: `--all` is not required --- docs/guide/migrating-from-v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index f337f4c5ce..28d7113424 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -9,7 +9,7 @@ npm install -g @vue/cli@4 In your existing projects, run: ``` -vue upgrade --all --next +vue upgrade --next ``` Please refer to the [Breaking Changes](#breaking-changes) section for all the possible breaking changes introduced. From 9476cfeb67b4aaa970843359989a937b07627f63 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Wed, 25 Sep 2019 23:03:06 +0800 Subject: [PATCH 04/27] docs: add more content --- docs/guide/migrating-from-v3.md | 96 ++++++++++++++++++++++++--------- 1 file changed, 70 insertions(+), 26 deletions(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index 28d7113424..2a0d49b236 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -1,38 +1,44 @@ # Migrating from v3 First, install the latest Vue CLI globally: -``` + +```sh npm install -g @vue/cli@4 ``` -## Auto Migration +## Upgrade All Plugins at Once In your existing projects, run: -``` + +```sh vue upgrade --next ``` -Please refer to the [Breaking Changes](#breaking-changes) section for all the possible breaking changes introduced. +And then see the following section for detailed breaking changes introduced in each package. ------ -## Manual Migration +## One-By-One Manual Migration If you want to do the migration manually and gradually, here are the tips: ### The Global `@vue/cli` Package The `vue upgrade` command was [redesigned](https://github.com/vuejs/vue-cli/pull/4090). + - Before: `vue upgrade [patch | minor | major]`, and it does nothing more than install the latest versions of Vue CLI plugins. - After: `vue upgrade [plugin-name]`. Aside from upgrading the plugins, it can run migrators from plugins to help you automate the migration process. For more options for this command, please run `vue upgrade --help`. ---- +------ When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra confirmation step](https://github.com/vuejs/vue-cli/pull/4275) if you have uncommitted changes in the current repository. ---- +![image](https://user-images.githubusercontent.com/3277634/65588457-23db5a80-dfba-11e9-9899-9dd72efc111e.png) + +------ When running `vue add vuex` or `vue add router`: + - in v3, only `vuex` or `vue-router` will be added to the project; - in v4, there will also be `@vue/cli-plugin-vuex` & `@vue/cli-plugin-router` installed. @@ -40,20 +46,34 @@ This currently does not make an actual difference for end users, but such design ### `@vue/cli-service` -* [#4323](https://github.com/vuejs/vue-cli/pull/4323) ensure consistent directory structure for all modes +#### `vue-cli-service build --mode development` + +In the past, when running the `build` command in the `development` mode, the `dist` folder layout would be different from the `production` mode. Now with the following two changes, the directory structures across all modes would be the same (file names are still different - no hashes in `development` mode): + +- [#4323](https://github.com/vuejs/vue-cli/pull/4323) ensure consistent directory structure for all modes +- [#4302](https://github.com/vuejs/vue-cli/pull/4302) move dev configs into serve command + +#### For SASS/SCSS Users -* [#4302](https://github.com/vuejs/vue-cli/pull/4302) move dev configs into serve command +Previously in Vue CLI v3, we shipped with `sass-loader@7` by default. -* [TODO: notes on less-loader version] +Recently `sass-loader@8` has been out and has changed its configuration format quite a lot. Here's the release notes: +`@vue/cli-service` will continue to support `sass-loader@7` in v4, but we strongly recommend you to take a look at the v8 release and upgrade to the latest version. -#### `vue.config.js` +#### For Less Users -* The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) +- [TODO: notes on less-loader version] -* [deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. +#### For CSS Module Users -* [Upgraded versions of several underlying webpack loaders](https://github.com/vuejs/vue-cli/pull/4331) [TODO elaborate this] +- [deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. + +#### Other Noticealbe Changes in `vue.config.js` + +- The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) + +- [Upgraded versions of several underlying webpack loaders](https://github.com/vuejs/vue-cli/pull/4331) [TODO elaborate this] If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. [TODO: add example here]. @@ -80,24 +100,25 @@ If your project was scaffolded with Vue CLI 3.0.x or earlier, you may need to ad It's also recommended to upgrade your ESLint to v5, and ESLint config versions to latest. (ESLint v6 support is still on the way) ---- +------ -[TODO][Notes on prettier config] +[TODO][Notes on prettier config version] ---- +------ (the following only affects development) The default value of `lintOnSave` option (when not specified) was [changed from `true` to `'default'`](https://github.com/vuejs/vue-cli/pull/3975). You can read more on the detailed explanation in the [documentation](https://cli.vuejs.org/config/#lintonsave). In a nutshell: + - In v3, by default, lint warnings, along with errors, will be displayed in the error overlay - In v4, by default, only lint errors will interrupt your development process. Warnings are only logged in the terminal console. ### `@vue/cli-plugin-pwa` -* [Upgraded to workbox v4](https://github.com/vuejs/vue-cli/pull/3915) -* [`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) +- [Upgraded to workbox v4](https://github.com/vuejs/vue-cli/pull/3915) +- [`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) ### `@vue/cli-plugin-e2e-cypress` @@ -106,9 +127,9 @@ We have now completely [dropped support for this legacy command](https://github. ### `@vue/cli-plugin-e2e-nightwatch` -* [#3388](https://github.com/vuejs/vue-cli/pull/3388) upgrade to nightwatch v1 -* [#3916](https://github.com/vuejs/vue-cli/pull/3916) upgrade to chromedriver v74 and make it a peer dependency -* [#3774](https://github.com/vuejs/vue-cli/pull/3774) remove support for legacy `vue-cli-service e2e` command +- [#3388](https://github.com/vuejs/vue-cli/pull/3388) upgrade to nightwatch v1 +- [#3916](https://github.com/vuejs/vue-cli/pull/3916) upgrade to chromedriver v74 and make it a peer dependency +- [#3774](https://github.com/vuejs/vue-cli/pull/3774) remove support for legacy `vue-cli-service e2e` command ### `@vue/cli-plugin-typescript` @@ -116,14 +137,37 @@ When using Typescript, the webpack resolve options now [prefer `ts(x)` file exte ### `@vue/cli-plugin-unit-jest` -* [Upgraded to jest v24](https://github.com/vuejs/vue-cli/pull/3870) +We've upgraded the bundled Jest from v23 to v24, so please read their [release notes](https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly) first. The full changelog is at . + +The `unit-jest` plugin now comes with 4 configuration presets: + +- `@vue/cli-plugin-unit-jest` The default preset for the most common type of projects +- `@vue/cli-plugin-unit-jest/presets/no-babel` If you don't have `@vue/cli-plugin-babel` installed and don't want to see babel files in the project +- `@vue/cli-plugin-unit-jest/presets/typescript` The preset with TypeScript support (but no TSX support) +- `@vue/cli-plugin-unit-jest/presets/typescript-and-babel` The preset with TypeScript (and TSX) and babel support. + +If you haven't changed the default Jest configurations (lies in either `jest.config.js` or the `jest` field in `package.json`) ever since project creation, you can now replace the massive configuration object with one single field: + +```js +module.exports = { + // Replace the following preset name with the one you want to use from the above list + preset: '@vue/cli-plugin-unit-jest' +} +``` + +(the `ts-jest`, `babel-jest` dependencies can also be removed after migrating config to use presets) -[TODO: More detailed information to be added…] +::: tip A Reminder +The default test environment in the new presets is jsdom@15, which differs from the default one in Jest 24 (jsdom@11). +This is to be aligned with the upcoming Jest 25 updates. +Most users won't be affected by this change. +For a detailed changelog with regard to jsdom, see +::: ### `@vue/cli-plugin-unit-mocha` -* Use mochapack instead of mocha-webpack, see changelog at . This change is not likely to affect actual usage. -* Upgraded to mocha 6, see +- Use mochapack instead of mocha-webpack, see changelog at . This change is not likely to affect actual usage. +- Upgraded to mocha 6, see [Mocha's changelog](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#600-0--2019-01-01) for more details. ### `@vue/cli-service-global` From 9c588f675648a7d63d61bd934b35729b7b73e95b Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Wed, 25 Sep 2019 23:12:40 +0800 Subject: [PATCH 05/27] docs: fix typo [ci skip] --- docs/guide/migrating-from-v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index 2a0d49b236..ff7309293d 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -69,7 +69,7 @@ Recently `sass-loader@8` has been out and has changed its configuration format q - [deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. -#### Other Noticealbe Changes in `vue.config.js` +#### Other Noticeable Changes in `vue.config.js` - The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) From 37eae28b159397af6d7e65c2d8d6dbada24c6da0 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Fri, 27 Sep 2019 00:03:19 +0800 Subject: [PATCH 06/27] docs: fix jest changelog link [ci skip] --- docs/guide/migrating-from-v3.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index ff7309293d..034e4a99c6 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -137,7 +137,8 @@ When using Typescript, the webpack resolve options now [prefer `ts(x)` file exte ### `@vue/cli-plugin-unit-jest` -We've upgraded the bundled Jest from v23 to v24, so please read their [release notes](https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly) first. The full changelog is at . +We've upgraded the bundled Jest from v23 to v24, so please read their [release notes](https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly) first. +Follow [this link](https://github.com/facebook/jest/blob/20ba4be9499d50ed0c9231b86d4a64ec8a6bd303/CHANGELOG.md#user-content-2400) for the full changelog. The `unit-jest` plugin now comes with 4 configuration presets: From 6c1c56817452b36e10fc616df7b603ffbaa8db53 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sat, 28 Sep 2019 23:28:28 +0800 Subject: [PATCH 07/27] docs: elaborate on babel plugin changes --- docs/guide/migrating-from-v3.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index 034e4a99c6..6b10479790 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -85,8 +85,27 @@ Please also notice that the following rules/loaders have been updated: ### `@vue/babel-preset-app`, `@vue/cli-plugin-babel` -- [Upgrade to core-js v3](https://github.com/vuejs/vue-cli/pull/3912). [TODO: detailed explanation] -- Use `@vue/cli-plugin-babel/preset` [TODO: auto migration & elaborate on this] +#### core-js + +The babel plugin requires a peer dependency, for the polyfills used in the transpiled code. + +In Vue CLI v3, the required core-js version is 2.x, it is now upgraded to 3.x. + +This migration is automated if you upgrade it through `vue upgrade babel --next`. But if you have custom polyfills introduced, you may need to manually update the polyfill names. + +[TODO: more detailed explanation] + +#### Babel Preset + +This migration is also automated if you upgrade it through `vue upgrade babel --next`. (TODO: pending ) + +- In v3, the default babel preset used in `babel.config.js` is `@vue/app`. +- In v4, we moved it to the plugin, so now it's named as `@vue/cli-plugin-babel/preset` + +It is because that `@vue/babel-preset-app` is actually an indirect dependency in the project. +It works because of npm's package hoisting. +But potential problems could still occur if the project has multiple conflicting indirect dependencies of the same package, or if the package manager puts stricter constraints on the dependency resolution (e.g. yarn plug'n'play or pnpm). +So we now moved it to the project's direct dependency (`@vue/cli-plugin-babel`) to make it more standard-compliant and less error-prone. ------ From 5f2adf64c9cfd65b48c76d72571529aa6b258c03 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 00:27:19 +0800 Subject: [PATCH 08/27] docs: elaborate on the less-loader version issue --- docs/guide/migrating-from-v3.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index 6b10479790..813762370d 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -63,7 +63,8 @@ Recently `sass-loader@8` has been out and has changed its configuration format q #### For Less Users -- [TODO: notes on less-loader version] +less-loader v4 is incompatible with less >= v3.10, see . +It's strongly recommended to upgrade to less-loader@5 if your project depends on it. #### For CSS Module Users @@ -73,7 +74,7 @@ Recently `sass-loader@8` has been out and has changed its configuration format q - The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) -- [Upgraded versions of several underlying webpack loaders](https://github.com/vuejs/vue-cli/pull/4331) [TODO elaborate this] +- [Upgraded versions of several underlying webpack loaders](https://github.com/vuejs/vue-cli/pull/4331) [TODO: elaborate this] If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. [TODO: add example here]. @@ -121,7 +122,7 @@ It's also recommended to upgrade your ESLint to v5, and ESLint config versions t ------ -[TODO][Notes on prettier config version] +[TODO:][Notes on prettier config version] ------ From 38e87d1aafa7451ade3038f1068f50caae722ff5 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 00:50:11 +0800 Subject: [PATCH 09/27] docs: finish eslint changelog [ci skip] --- docs/guide/migrating-from-v3.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index 813762370d..6f7307bb68 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -122,10 +122,22 @@ It's also recommended to upgrade your ESLint to v5, and ESLint config versions t ------ -[TODO:][Notes on prettier config version] +#### The Prettier Preset + +The old implementation of our prettier preset is flawed. We've updated the default template since Vue CLI v3.10. + +It now requires `eslint`, `eslint-plugin-prettier` and `prettier` as peer dependencies, following the [standard practice in the ESLint ecosystem](https://github.com/eslint/eslint/issues/3458). + +For older projects, if you encountered issues like `Cannot find module: eslint-plugin-prettier`, please run the following command to fix it: + +```sh +npm install --sav-dev eslint@5 @vue/eslint-config-prettier@5 eslint-plugin-prettier prettier +``` ------ +#### `lintOnSave` options + (the following only affects development) The default value of `lintOnSave` option (when not specified) was [changed from `true` to `'default'`](https://github.com/vuejs/vue-cli/pull/3975). You can read more on the detailed explanation in the [documentation](https://cli.vuejs.org/config/#lintonsave). From 607804a1676cadcce8b0bcda025f91c7ee50a5f8 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 01:12:29 +0800 Subject: [PATCH 10/27] docs: more on webpack configs [ci skip] --- docs/guide/migrating-from-v3.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/guide/migrating-from-v3.md b/docs/guide/migrating-from-v3.md index 6f7307bb68..887b06f344 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/guide/migrating-from-v3.md @@ -68,21 +68,31 @@ It's strongly recommended to upgrade to less-loader@5 if your project depends on #### For CSS Module Users -- [deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. +- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. -#### Other Noticeable Changes in `vue.config.js` +#### `vue.config.js` options -- The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) +The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) is now [removed](https://github.com/vuejs/vue-cli/pull/4388) -- [Upgraded versions of several underlying webpack loaders](https://github.com/vuejs/vue-cli/pull/4331) [TODO: elaborate this] +#### `chainWebpack` / `configureWebpack` If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. [TODO: add example here]. -Please also notice that the following rules/loaders have been updated: +The following rules have been updated: -1. [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20), the `debug` option was renamed to `logLevel` -2. [use EnvironmentPlugin instead of DefinePlugin for `process.env.*` vars](https://github.com/vuejs/vue-cli/pull/3782), [TODO: detailed explanation] -3. [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) +- [use EnvironmentPlugin instead of DefinePlugin for `process.env.*` vars](https://github.com/vuejs/vue-cli/pull/3782), [TODO: detailed explanation and example] +- [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) + +#### Underlying Loaders / Plugins + +Not likely to affect users unless you've customized their options via `chainWebpack` / `configureWebpack` + +Several underlying webpack loaders and plugins have been upgraded, most changes are trivial: + +- css-loader [TODO: elaborate this] +- url-loader [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) +- file-loader [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) +- copy-webpack-plugin [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) ### `@vue/babel-preset-app`, `@vue/cli-plugin-babel` From 1886c6e05cffda9daf9a90ed55a0de09c63179dc Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 01:18:57 +0800 Subject: [PATCH 11/27] docs: move migrating-to-v3 to first-level nav --- docs/.vuepress/config.js | 5 ++--- .../migrating-from-v3.md => migrating-from-v3/README.md} | 8 ++++++-- 2 files changed, 8 insertions(+), 5 deletions(-) rename docs/{guide/migrating-from-v3.md => migrating-from-v3/README.md} (99%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 6dd221230e..b5a06c4a36 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -87,7 +87,7 @@ module.exports = { }, { text: 'Migrating From v3', - link: '/guide/migrating-from-v3' + link: '/migrating-from-v3/' }, { text: 'Changelog', @@ -119,8 +119,7 @@ module.exports = { '/guide/mode-and-env', '/guide/build-targets', '/guide/deployment', - '/guide/troubleshooting', - '/guide/migrating-from-v3' + '/guide/troubleshooting' ] } ], diff --git a/docs/guide/migrating-from-v3.md b/docs/migrating-from-v3/README.md similarity index 99% rename from docs/guide/migrating-from-v3.md rename to docs/migrating-from-v3/README.md index 887b06f344..9ce81ed872 100644 --- a/docs/guide/migrating-from-v3.md +++ b/docs/migrating-from-v3/README.md @@ -1,3 +1,7 @@ +--- +sidebar: auto +--- + # Migrating from v3 First, install the latest Vue CLI globally: @@ -22,7 +26,7 @@ And then see the following section for detailed breaking changes introduced in e If you want to do the migration manually and gradually, here are the tips: -### The Global `@vue/cli` Package +### The Global `@vue/cli` The `vue upgrade` command was [redesigned](https://github.com/vuejs/vue-cli/pull/4090). @@ -94,7 +98,7 @@ Several underlying webpack loaders and plugins have been upgraded, most changes - file-loader [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) - copy-webpack-plugin [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) -### `@vue/babel-preset-app`, `@vue/cli-plugin-babel` +### `@vue/cli-plugin-babel`, `@vue/babel-preset-app` #### core-js From 8399de54c36b00adbf3afa821eacd799d91cf69f Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 01:27:28 +0800 Subject: [PATCH 12/27] docs: elaborate on css-loader changes [ci skip] --- docs/migrating-from-v3/README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 9ce81ed872..696b65b669 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -91,9 +91,13 @@ The following rules have been updated: Not likely to affect users unless you've customized their options via `chainWebpack` / `configureWebpack` -Several underlying webpack loaders and plugins have been upgraded, most changes are trivial: +css-loader was upgraded from v1 to v3: + +- [v2 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v2.0.0) +- [v3 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v3.0.0) + +Several other underlying webpack loaders and plugins have been upgraded, with mostly trivial changes: -- css-loader [TODO: elaborate this] - url-loader [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) - file-loader [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) - copy-webpack-plugin [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) From 5d63897df7110ef88b80035a706cf44d129dd159 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 16:08:02 +0800 Subject: [PATCH 13/27] docs: finish nightwatch guide [ci skip] --- docs/migrating-from-v3/README.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 696b65b669..661f57e773 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -67,8 +67,8 @@ Recently `sass-loader@8` has been out and has changed its configuration format q #### For Less Users -less-loader v4 is incompatible with less >= v3.10, see . -It's strongly recommended to upgrade to less-loader@5 if your project depends on it. +`less-loader` v4 is incompatible with `less` >= v3.10, see . +It's strongly recommended to upgrade to `less-loader@5` if your project depends on it. #### For CSS Module Users @@ -91,16 +91,16 @@ The following rules have been updated: Not likely to affect users unless you've customized their options via `chainWebpack` / `configureWebpack` -css-loader was upgraded from v1 to v3: +`css-loader` was upgraded from v1 to v3: - [v2 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v2.0.0) - [v3 changelog](https://github.com/webpack-contrib/css-loader/releases/tag/v3.0.0) Several other underlying webpack loaders and plugins have been upgraded, with mostly trivial changes: -- url-loader [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) -- file-loader [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) -- copy-webpack-plugin [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) +- `url-loader` [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) +- `file-loader` [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) +- `copy-webpack-plugin` [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) ### `@vue/cli-plugin-babel`, `@vue/babel-preset-app` @@ -108,7 +108,7 @@ Several other underlying webpack loaders and plugins have been upgraded, with mo The babel plugin requires a peer dependency, for the polyfills used in the transpiled code. -In Vue CLI v3, the required core-js version is 2.x, it is now upgraded to 3.x. +In Vue CLI v3, the required `core-js` version is 2.x, it is now upgraded to 3.x. This migration is automated if you upgrade it through `vue upgrade babel --next`. But if you have custom polyfills introduced, you may need to manually update the polyfill names. @@ -116,7 +116,7 @@ This migration is automated if you upgrade it through `vue upgrade babel --next` #### Babel Preset -This migration is also automated if you upgrade it through `vue upgrade babel --next`. (TODO: pending ) +This migration is also automated if you upgrade it through `vue upgrade babel --next`. - In v3, the default babel preset used in `babel.config.js` is `@vue/app`. - In v4, we moved it to the plugin, so now it's named as `@vue/cli-plugin-babel/preset` @@ -167,6 +167,8 @@ In a nutshell: ### `@vue/cli-plugin-pwa` +[TODO:] + - [Upgraded to workbox v4](https://github.com/vuejs/vue-cli/pull/3915) - [`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) @@ -177,9 +179,16 @@ We have now completely [dropped support for this legacy command](https://github. ### `@vue/cli-plugin-e2e-nightwatch` -- [#3388](https://github.com/vuejs/vue-cli/pull/3388) upgrade to nightwatch v1 -- [#3916](https://github.com/vuejs/vue-cli/pull/3916) upgrade to chromedriver v74 and make it a peer dependency -- [#3774](https://github.com/vuejs/vue-cli/pull/3774) remove support for legacy `vue-cli-service e2e` command +Nightwatch.js has been upgraded from 0.9 to 1.x. Be sure to read the [Nightwatch migration guides](https://github.com/nightwatchjs/nightwatch/wiki/Migrating-to-Nightwatch-1.0) first. + +The bundled config and generated tests [have been completely overhauled](https://github.com/vuejs/vue-cli/pull/4541). Please follow the link for more details. Most use cases in Vue CLI v3 are still supported. They are just new features. + +As ChromeDriver has changed its version strategy since version 73, we've made it a peer dependency in the project. +A simple browser version check is implemented in the plugin, so if you've upgraded to an incompatible version of Chrome, there will be a warning to prompt you to upgrade the depended ChromeDriver version. + +------ + +As in the cypress plugin, the support for legacy `vue-cli-service e2e` command has also been removed. ### `@vue/cli-plugin-typescript` From 5fa153ac5766aa98efe486da6b0463259b96a52f Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sun, 29 Sep 2019 16:22:49 +0800 Subject: [PATCH 14/27] docs: link to workbox v4 release notes [ci skip] --- docs/migrating-from-v3/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 661f57e773..bd41179ead 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -167,10 +167,9 @@ In a nutshell: ### `@vue/cli-plugin-pwa` -[TODO:] +The underlying workbox-webpack-plugin has been upgraded from v3 to v4. See [the release notes here](https://github.com/GoogleChrome/workbox/releases/tag/v4.0.0). -- [Upgraded to workbox v4](https://github.com/vuejs/vue-cli/pull/3915) -- [`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) +[`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) [TODO: elaborate] ### `@vue/cli-plugin-e2e-cypress` From e558f8ef2e592fbcf53738472b9c36d3af201a50 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Mon, 30 Sep 2019 23:26:58 +0800 Subject: [PATCH 15/27] docs: [wip] detailed explanation on vue.config.js --- docs/migrating-from-v3/README.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index bd41179ead..0f390cf7d4 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -80,11 +80,36 @@ The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) #### `chainWebpack` / `configureWebpack` -If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. [TODO: add example here]. +##### The `minimizer` Method in `chainWebpack` -The following rules have been updated: +If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. + +For example, if you want to enable `drop_console` option in the terser plugin. +In v3, you can do this in `chainWebpack`: + +```js +module.exports = { + chainWebpack: (config) => { + // TODO: + // terserOptions: { compress: { drop_console: true } } + } +} +``` + +In v4, it's changed to: + +```js +// TODO: +``` + +##### The `define` Plugin is Changed to `process-env` and Uses `EnvironmentPlugin` Underlyingly + +See [#3782](https://github.com/vuejs/vue-cli/pull/3782). + +[TODO: detailed explanation and example for defining `process.env.*` vars] + +##### Other Changes -- [use EnvironmentPlugin instead of DefinePlugin for `process.env.*` vars](https://github.com/vuejs/vue-cli/pull/3782), [TODO: detailed explanation and example] - [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) #### Underlying Loaders / Plugins From 84058d1d2a907fafd12a008aa90ddf7bb83602d9 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Wed, 2 Oct 2019 17:49:52 +0800 Subject: [PATCH 16/27] docs: add examples for terser; add router & vuex directory change --- docs/migrating-from-v3/README.md | 34 ++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 0f390cf7d4..9f447b9d1f 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -43,11 +43,18 @@ When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra con When running `vue add vuex` or `vue add router`: -- in v3, only `vuex` or `vue-router` will be added to the project; -- in v4, there will also be `@vue/cli-plugin-vuex` & `@vue/cli-plugin-router` installed. +- In v3, only `vuex` or `vue-router` will be added to the project; +- In v4, there will also be `@vue/cli-plugin-vuex` & `@vue/cli-plugin-router` installed. This currently does not make an actual difference for end users, but such design allows us to add more features for vuex & vue-router users later. +For preset and plugin authors, there are several noteworthy changes in the two plugins: + +- The default directory structure was changed: + - `src/store.js` moved to `src/store/index.js`; + - `src/router.js` renamed to `src/router/index.js`; +- The `router` & `routerHistoryMode` options in `preset.json` is still supported for compatibility reason. But it's now recommended to use `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` for better consistency. + ### `@vue/cli-service` #### `vue-cli-service build --mode development` @@ -82,16 +89,18 @@ The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) ##### The `minimizer` Method in `chainWebpack` -If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config. +If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config For example, if you want to enable `drop_console` option in the terser plugin. -In v3, you can do this in `chainWebpack`: +In v3, you may do this in `chainWebpack`: ```js +const TerserPlugin = require('terser-webpack-plugin') module.exports = { chainWebpack: (config) => { - // TODO: - // terserOptions: { compress: { drop_console: true } } + config.optimization.minimizer([ + new TerserPlugin({ terserOptions: { compress: { drop_console: true } } }) + ]) } } ``` @@ -99,7 +108,16 @@ module.exports = { In v4, it's changed to: ```js -// TODO: +module.exports = { + chainWebpack: (config) => { + if (process.env.NODE_ENV === 'production') { + config.optimization.minimizer('terser').tap((args) => { + args[0].terserOptions.compress.drop_console = true + return args + }) + } + } +} ``` ##### The `define` Plugin is Changed to `process-env` and Uses `EnvironmentPlugin` Underlyingly @@ -137,7 +155,7 @@ In Vue CLI v3, the required `core-js` version is 2.x, it is now upgraded to 3.x. This migration is automated if you upgrade it through `vue upgrade babel --next`. But if you have custom polyfills introduced, you may need to manually update the polyfill names. -[TODO: more detailed explanation] +[TODO: more detailed explanation on polyfills] #### Babel Preset From 57be2f251314ee6bb87565e8c5f9db29d834877e Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Wed, 2 Oct 2019 22:03:32 +0800 Subject: [PATCH 17/27] docs: mention `api.hasPlugin('vue-router')` [ci skip] --- docs/migrating-from-v3/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 9f447b9d1f..1dd6374e1a 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -54,6 +54,7 @@ For preset and plugin authors, there are several noteworthy changes in the two p - `src/store.js` moved to `src/store/index.js`; - `src/router.js` renamed to `src/router/index.js`; - The `router` & `routerHistoryMode` options in `preset.json` is still supported for compatibility reason. But it's now recommended to use `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` for better consistency. +- `api.hasPlugin('vue-router')` is no longer supported. It's now `api.hasPlugin('router')`. ### `@vue/cli-service` From 38d291d8d93a3ebb67c651107a6971a10ab9df53 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sat, 5 Oct 2019 00:44:56 +0800 Subject: [PATCH 18/27] docs: add subtitles [ci skip] --- docs/migrating-from-v3/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 1dd6374e1a..4545b70f2b 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -28,18 +28,18 @@ If you want to do the migration manually and gradually, here are the tips: ### The Global `@vue/cli` -The `vue upgrade` command was [redesigned](https://github.com/vuejs/vue-cli/pull/4090). +#### [Redesigned](https://github.com/vuejs/vue-cli/pull/4090) `vue upgrade` - Before: `vue upgrade [patch | minor | major]`, and it does nothing more than install the latest versions of Vue CLI plugins. - After: `vue upgrade [plugin-name]`. Aside from upgrading the plugins, it can run migrators from plugins to help you automate the migration process. For more options for this command, please run `vue upgrade --help`. ------- +#### Extra Confirmation Step To Avoid Overwriting When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra confirmation step](https://github.com/vuejs/vue-cli/pull/4275) if you have uncommitted changes in the current repository. ![image](https://user-images.githubusercontent.com/3277634/65588457-23db5a80-dfba-11e9-9899-9dd72efc111e.png) ------- +#### Vue Router and Vuex Now Have Corresponding CLI Plugins When running `vue add vuex` or `vue add router`: From 3ea9df904bbd975abaedbd3f62e088fcbab21e67 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Fri, 11 Oct 2019 16:28:09 +0800 Subject: [PATCH 19/27] docs: update descriptions to reflect rc.8 changes --- docs/migrating-from-v3/README.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 4545b70f2b..c5ade00c06 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -111,22 +111,14 @@ In v4, it's changed to: ```js module.exports = { chainWebpack: (config) => { - if (process.env.NODE_ENV === 'production') { - config.optimization.minimizer('terser').tap((args) => { - args[0].terserOptions.compress.drop_console = true - return args - }) - } + config.optimization.minimizer('terser').tap((args) => { + args[0].terserOptions.compress.drop_console = true + return args + }) } } ``` -##### The `define` Plugin is Changed to `process-env` and Uses `EnvironmentPlugin` Underlyingly - -See [#3782](https://github.com/vuejs/vue-cli/pull/3782). - -[TODO: detailed explanation and example for defining `process.env.*` vars] - ##### Other Changes - [The `pug-plain` rule was renamed to `pug-plain-loader`](https://github.com/vuejs/vue-cli/pull/4230) @@ -145,6 +137,7 @@ Several other underlying webpack loaders and plugins have been upgraded, with mo - `url-loader` [from v1 to v2](https://github.com/webpack-contrib/url-loader/releases/tag/v2.0.0) - `file-loader` [from v3 to v4](https://github.com/webpack-contrib/file-loader/releases/tag/v4.0.0) - `copy-webpack-plugin` [from v4 to v5](https://github.com/webpack-contrib/copy-webpack-plugin/blob/master/CHANGELOG.md#500-2019-02-20) +- `terser-webpack-plugin` [from v1 to v2](https://github.com/vuejs/vue-cli/pull/4676) ### `@vue/cli-plugin-babel`, `@vue/babel-preset-app` @@ -154,9 +147,7 @@ The babel plugin requires a peer dependency, for the polyfills used in the trans In Vue CLI v3, the required `core-js` version is 2.x, it is now upgraded to 3.x. -This migration is automated if you upgrade it through `vue upgrade babel --next`. But if you have custom polyfills introduced, you may need to manually update the polyfill names. - -[TODO: more detailed explanation on polyfills] +This migration is automated if you upgrade it through `vue upgrade babel --next`. But if you have custom polyfills introduced, you may need to manually update the polyfill names (For more details, see [core-js changelog](https://github.com/zloirock/core-js/blob/master/CHANGELOG.md#L279-L297)). #### Babel Preset @@ -213,7 +204,7 @@ In a nutshell: The underlying workbox-webpack-plugin has been upgraded from v3 to v4. See [the release notes here](https://github.com/GoogleChrome/workbox/releases/tag/v4.0.0). -[`manifest.json` is now generated by the plugin itself](https://github.com/vuejs/vue-cli/pull/2981) [TODO: elaborate] +There's also a `pwa.manifestOptions` field available (you can set it in the `vue.config.js`). With this new option, `manifest.json` will be generated from the config object rather than directly copied from the `public` folder. This provides a more consistent interface to manage your PWA configurations. (Note, it is an opt-in feature. Related PRs: [#2981](https://github.com/vuejs/vue-cli/pull/2981), [#4664](https://github.com/vuejs/vue-cli/pull/4664)) ### `@vue/cli-plugin-e2e-cypress` From 70e94b7ec12fd22c68b18d72f482384918a8e6c0 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Fri, 11 Oct 2019 16:40:51 +0800 Subject: [PATCH 20/27] docs: some grammar corrections [ci skip] --- docs/migrating-from-v3/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index c5ade00c06..278310353f 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -24,13 +24,13 @@ And then see the following section for detailed breaking changes introduced in e ## One-By-One Manual Migration -If you want to do the migration manually and gradually, here are the tips: +If you want to migrate manually and gradually, here are the tips: ### The Global `@vue/cli` #### [Redesigned](https://github.com/vuejs/vue-cli/pull/4090) `vue upgrade` -- Before: `vue upgrade [patch | minor | major]`, and it does nothing more than install the latest versions of Vue CLI plugins. +- Before: `vue upgrade [patch | minor | major]`, and it does nothing more than installing the latest versions of Vue CLI plugins. - After: `vue upgrade [plugin-name]`. Aside from upgrading the plugins, it can run migrators from plugins to help you automate the migration process. For more options for this command, please run `vue upgrade --help`. #### Extra Confirmation Step To Avoid Overwriting @@ -46,7 +46,7 @@ When running `vue add vuex` or `vue add router`: - In v3, only `vuex` or `vue-router` will be added to the project; - In v4, there will also be `@vue/cli-plugin-vuex` & `@vue/cli-plugin-router` installed. -This currently does not make an actual difference for end users, but such design allows us to add more features for vuex & vue-router users later. +This currently does not make an actual difference for end-users, but such design allows us to add more features for vuex & vue-router users later. For preset and plugin authors, there are several noteworthy changes in the two plugins: @@ -80,7 +80,7 @@ It's strongly recommended to upgrade to `less-loader@5` if your project depends #### For CSS Module Users -- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For more detailed explanation please follow the link. +- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For a more detailed explanation please follow the link. #### `vue.config.js` options @@ -92,7 +92,7 @@ The already-deprecated [`baseUrl` option](https://cli.vuejs.org/config/#baseurl) If you've customized the internal rules with `chainWebpack`, please notice that `webpack-chain` was updated from v4 to v6, the most noticeable change is the `minimizer` config -For example, if you want to enable `drop_console` option in the terser plugin. +For example, if you want to enable the `drop_console` option in the terser plugin. In v3, you may do this in `chainWebpack`: ```js @@ -156,7 +156,7 @@ This migration is also automated if you upgrade it through `vue upgrade babel -- - In v3, the default babel preset used in `babel.config.js` is `@vue/app`. - In v4, we moved it to the plugin, so now it's named as `@vue/cli-plugin-babel/preset` -It is because that `@vue/babel-preset-app` is actually an indirect dependency in the project. +It is because that `@vue/babel-preset-app` is indeed an indirect dependency on the project. It works because of npm's package hoisting. But potential problems could still occur if the project has multiple conflicting indirect dependencies of the same package, or if the package manager puts stricter constraints on the dependency resolution (e.g. yarn plug'n'play or pnpm). So we now moved it to the project's direct dependency (`@vue/cli-plugin-babel`) to make it more standard-compliant and less error-prone. @@ -171,7 +171,7 @@ This won't affect projects scaffolded with Vue CLI 3.1 or later. If your project was scaffolded with Vue CLI 3.0.x or earlier, you may need to add `eslint@4` to your project dependencies (This is automated if you upgrade the plugin using `vue upgrade eslint --next`). -It's also recommended to upgrade your ESLint to v5, and ESLint config versions to latest. (ESLint v6 support is still on the way) +It's also recommended to upgrade your ESLint to v5, and ESLint config versions to the latest. (ESLint v6 support is still on the way) ------ From ce9da936d115e7a57a5004f89a9737403fd9d7d9 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Fri, 11 Oct 2019 16:55:17 +0800 Subject: [PATCH 21/27] docs: add whitespace handling changes [ci skip] --- docs/migrating-from-v3/README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 278310353f..cbfddb2fb7 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -58,6 +58,35 @@ For preset and plugin authors, there are several noteworthy changes in the two p ### `@vue/cli-service` +#### Whitespace handling in the template block + +To get a smaller bundle, we've disabled the `preserveWhitespace` option of `vue-template-compiler` by default in Vue CLI v3. +This set comes with some caveats, however. +Luckily, since the Vue 2.6 release, we can now have finer control over the whitespace handling, with the [new `whitespace` option](https://github.com/vuejs/vue/issues/9208#issuecomment-450012518). So we decided to switch over to use this new option by default in Vue CLI v4. + +Take the following template as an example: + +```html +

+ Welcome to Vue.js world. + Have fun! +

+``` + +With `preserveWhitespace: false`, all whitespaces between tags are removed, so it was compiled as: + +```html +

Welcome to Vue.jsworld. Have fun!

+``` + +With `whitespace: 'condense'`, it is now compiled as: + +```html +

Welcome to Vue.js world. Have fun!

+``` + +Note the **inline** whitespace between tags is now preserved. + #### `vue-cli-service build --mode development` In the past, when running the `build` command in the `development` mode, the `dist` folder layout would be different from the `production` mode. Now with the following two changes, the directory structures across all modes would be the same (file names are still different - no hashes in `development` mode): From b09019a8efd3b877d17bb7397a9274f1001d3afd Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Fri, 11 Oct 2019 17:04:10 +0800 Subject: [PATCH 22/27] docs: @4 -> @next [ci skip] --- docs/migrating-from-v3/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index cbfddb2fb7..2b12a08d23 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -7,7 +7,7 @@ sidebar: auto First, install the latest Vue CLI globally: ```sh -npm install -g @vue/cli@4 +npm install -g @vue/cli@next ``` ## Upgrade All Plugins at Once From e282528d5a341cf1e556c54cd09e7faf9d66abf2 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Fri, 11 Oct 2019 17:05:05 +0800 Subject: [PATCH 23/27] docs: blank lines [ci skip] --- docs/migrating-from-v3/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 2b12a08d23..e618564ede 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -61,7 +61,9 @@ For preset and plugin authors, there are several noteworthy changes in the two p #### Whitespace handling in the template block To get a smaller bundle, we've disabled the `preserveWhitespace` option of `vue-template-compiler` by default in Vue CLI v3. + This set comes with some caveats, however. + Luckily, since the Vue 2.6 release, we can now have finer control over the whitespace handling, with the [new `whitespace` option](https://github.com/vuejs/vue/issues/9208#issuecomment-450012518). So we decided to switch over to use this new option by default in Vue CLI v4. Take the following template as an example: From cf254323524789e0197bc1890f5ffe118fad80d7 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sat, 12 Oct 2019 12:09:29 +0800 Subject: [PATCH 24/27] Update docs/migrating-from-v3/README.md Co-Authored-By: Natalia Tepluhina --- docs/migrating-from-v3/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index e618564ede..9479f0c8ac 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -44,7 +44,7 @@ When running `vue invoke` / `vue add` / `vue upgrade`, there's now an [extra con When running `vue add vuex` or `vue add router`: - In v3, only `vuex` or `vue-router` will be added to the project; -- In v4, there will also be `@vue/cli-plugin-vuex` & `@vue/cli-plugin-router` installed. +- In v4, there will also be `@vue/cli-plugin-vuex` or `@vue/cli-plugin-router` installed. This currently does not make an actual difference for end-users, but such design allows us to add more features for vuex & vue-router users later. From 89677738174b4a1c3e7e281b9b8fe3701387c102 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sat, 12 Oct 2019 12:09:42 +0800 Subject: [PATCH 25/27] Update docs/migrating-from-v3/README.md Co-Authored-By: Natalia Tepluhina --- docs/migrating-from-v3/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 9479f0c8ac..3ed5d7c0b6 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -46,7 +46,7 @@ When running `vue add vuex` or `vue add router`: - In v3, only `vuex` or `vue-router` will be added to the project; - In v4, there will also be `@vue/cli-plugin-vuex` or `@vue/cli-plugin-router` installed. -This currently does not make an actual difference for end-users, but such design allows us to add more features for vuex & vue-router users later. +This currently does not make an actual difference for end-users, but such design allows us to add more features for Vuex and Vue Router users later. For preset and plugin authors, there are several noteworthy changes in the two plugins: From a88dfb8b7ba8bc2cb4bfe4d200391aa2caac3716 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sat, 12 Oct 2019 12:10:09 +0800 Subject: [PATCH 26/27] Update docs/migrating-from-v3/README.md Co-Authored-By: Natalia Tepluhina --- docs/migrating-from-v3/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index 3ed5d7c0b6..f2dd67eb6f 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -53,7 +53,7 @@ For preset and plugin authors, there are several noteworthy changes in the two p - The default directory structure was changed: - `src/store.js` moved to `src/store/index.js`; - `src/router.js` renamed to `src/router/index.js`; -- The `router` & `routerHistoryMode` options in `preset.json` is still supported for compatibility reason. But it's now recommended to use `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` for better consistency. +- The `router` & `routerHistoryMode` options in `preset.json` are still supported for compatibility reasons. But it's now recommended to use `plugins: { '@vue/cli-plugin-router': { historyMode: true } }` for better consistency. - `api.hasPlugin('vue-router')` is no longer supported. It's now `api.hasPlugin('router')`. ### `@vue/cli-service` From 6f215462d448a8a4d34c998590fd56e473d5f038 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Sat, 12 Oct 2019 12:10:23 +0800 Subject: [PATCH 27/27] Update docs/migrating-from-v3/README.md Co-Authored-By: Natalia Tepluhina --- docs/migrating-from-v3/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating-from-v3/README.md b/docs/migrating-from-v3/README.md index f2dd67eb6f..1ec3348df7 100644 --- a/docs/migrating-from-v3/README.md +++ b/docs/migrating-from-v3/README.md @@ -111,7 +111,7 @@ It's strongly recommended to upgrade to `less-loader@5` if your project depends #### For CSS Module Users -- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to css-loader v3 and the config format has been changed. For a more detailed explanation please follow the link. +- [Deprecate `css.modules` in favor of `css.requireModuleExtension`](https://github.com/vuejs/vue-cli/pull/4387). This is because we've upgraded to `css-loader` v3 and the config format has been changed. For a more detailed explanation please follow the link. #### `vue.config.js` options