Skip to content

Commit 20c96c4

Browse files
NataliaTepluhinahaoqunjiang
NataliaTepluhina
authored and
haoqunjiang
committed
docs: move core plugins docs to documentation website (#4120)
Also, created a script to generate docs
1 parent f3d2c1c commit 20c96c4

File tree

12 files changed

+535
-12
lines changed

12 files changed

+535
-12
lines changed

‎docs/.vuepress/config.js

+17-11
Original file line numberDiff line numberDiff line change
@@ -83,16 +83,7 @@ module.exports = {
8383
},
8484
{
8585
text: 'Plugins',
86-
items: [
87-
{ text: 'Babel', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-babel' },
88-
{ text: 'TypeScript', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-typescript' },
89-
{ text: 'ESLint', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint' },
90-
{ text: 'PWA', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa' },
91-
{ text: 'Jest', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest' },
92-
{ text: 'Mocha', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha' },
93-
{ text: 'Cypress', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-cypress' },
94-
{ text: 'Nightwatch', link: 'https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch' }
95-
]
86+
link: '/core-plugins/'
9687
},
9788
{
9889
text: 'Changelog',
@@ -147,7 +138,22 @@ module.exports = {
147138
'/dev-guide/ui-localization.md'
148139
]
149140
}
150-
]
141+
],
142+
'/core-plugins/': [{
143+
title: 'Core Vue CLI Plugins',
144+
collapsable: false,
145+
children: [
146+
'/core-plugins/babel.md',
147+
'/core-plugins/typescript.md',
148+
'/core-plugins/eslint.md',
149+
'/core-plugins/pwa.md',
150+
'/core-plugins/unit-jest.md',
151+
'/core-plugins/unit-mocha.md',
152+
'/core-plugins/e2e-cypress.md',
153+
'/core-plugins/e2e-nightwatch.md'
154+
]
155+
}],
156+
151157
}
152158
},
153159
'/zh/': {

‎docs/core-plugins/README.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Plugins
2+
3+
Vue CLI uses a plugin-based architecture. If you inspect a newly created project's `package.json`, you will find dependencies that start with `@vue/cli-plugin-`. Plugins can modify the internal webpack configuration and inject commands to `vue-cli-service`. Most of the features listed during the project creation process are implemented as plugins.
4+
5+
This section contains documentation for core Vue CLI plugins:
6+
7+
- [Babel](babel.md)
8+
- [TypeScript](typescript.md)
9+
- [ESLint](eslint.md)
10+
- [PWA](pwa.md)
11+
- [Jest](unit-jest.md)
12+
- [Mocha](unit-mocha.md)
13+
- [Cypress](e2e-cypress.md)
14+
- [Nightwatch](e2e-nightwatch.md)

‎docs/core-plugins/babel.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# @vue/cli-plugin-babel
2+
3+
> babel plugin for vue-cli
4+
5+
## Configuration
6+
7+
Uses Babel 7 + `babel-loader` + [@vue/babel-preset-app](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app) by default, but can be configured via `babel.config.js` to use any other Babel presets or plugins.
8+
9+
By default, `babel-loader` excludes files inside `node_modules` dependencies. If you wish to explicitly transpile a dependency module, you will need to add it to the `transpileDependencies` option in `vue.config.js`:
10+
11+
``` js
12+
module.exports = {
13+
transpileDependencies: [
14+
// can be string or regex
15+
'my-dep',
16+
/other-dep/
17+
]
18+
}
19+
```
20+
21+
## Caching
22+
23+
[cache-loader](https://github.com/webpack-contrib/cache-loader) is enabled by default and cache is stored in `<projectRoot>/node_modules/.cache/babel-loader`.
24+
25+
## Parallelization
26+
27+
[thread-loader](https://github.com/webpack-contrib/thread-loader) is enabled by default when the machine has more than 1 CPU cores. This can be turned off by setting `parallel: false` in `vue.config.js`.
28+
29+
## Installing in an Already Created Project
30+
31+
``` sh
32+
vue add @vue/babel
33+
```
34+
35+
## Injected webpack-chain Rules
36+
37+
- `config.rule('js')`
38+
- `config.rule('js').use('babel-loader')`
39+
- `config.rule('js').use('cache-loader')`

‎docs/core-plugins/e2e-cypress.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# @vue/cli-plugin-e2e-cypress
2+
3+
> e2e-cypress plugin for vue-cli
4+
5+
This adds E2E testing support using [Cypress](https://www.cypress.io/).
6+
7+
Cypress offers a rich interactive interface for running E2E tests, but currently only supports running the tests in Chromium. If you have a hard requirement on E2E testing in multiple browsers, consider using the Selenium-based [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch).
8+
9+
## Injected Commands
10+
11+
- **`vue-cli-service test:e2e`**
12+
13+
Run e2e tests with `cypress run`.
14+
15+
By default it launches Cypress in interactive mode with a GUI. If you want to run the tests in headless mode (e.g. for CI), you can do so with the `--headless` option.
16+
17+
The command automatically starts a server in production mode to run the e2e tests against. If you want to run the tests multiple times without having to restart the server every time, you can start the server with `vue-cli-service serve --mode production` in one terminal, and then run e2e tests against that server using the `--url` option.
18+
19+
Options:
20+
21+
```
22+
--headless run in headless mode without GUI
23+
--mode specify the mode the dev server should run in. (default: production)
24+
--url run e2e tests against given url instead of auto-starting dev server
25+
-s, --spec (headless only) runs a specific spec file. defaults to "all"
26+
```
27+
28+
Additionally:
29+
30+
- In GUI mode, [all Cypress CLI options for `cypress open` are also supported](https://docs.cypress.io/guides/guides/command-line.html#cypress-open);
31+
- In `--headless` mode, [all Cypress CLI options for `cypress run` are also supported](https://docs.cypress.io/guides/guides/command-line.html#cypress-run).
32+
33+
Examples :
34+
- Run Cypress in headless mode for a specific file: `vue-cli-service test:e2e --headless --spec tests/e2e/specs/actions.spec.js`
35+
36+
## Configuration
37+
38+
We've pre-configured Cypress to place most of the e2e testing related files under `<projectRoot>/tests/e2e`. You can also check out [how to configure Cypress via `cypress.json`](https://docs.cypress.io/guides/references/configuration.html#Options).
39+
40+
## Environment Variables
41+
42+
Cypress doesn't load .env files for your test files the same way as `vue-cli` does for your [application code](https://cli.vuejs.org/guide/mode-and-env.html#using-env-variables-in-client-side-code). Cypress supports a few ways to [define env variables](https://docs.cypress.io/guides/guides/environment-variables.html#) but the easiest one is to use .json files (either `cypress.json` or `cypress.env.json`) to define environment variables. Keep in mind those variables are accessible via `Cypress.env` function instead of regular `process.env` object.
43+
44+
## Installing in an Already Created Project
45+
46+
``` sh
47+
vue add @vue/e2e-cypress
48+
```

‎docs/core-plugins/e2e-nightwatch.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# @vue/cli-plugin-e2e-nightwatch
2+
3+
> e2e-nightwatch plugin for vue-cli
4+
5+
## Injected Commands
6+
7+
- **`vue-cli-service test:e2e`**
8+
9+
run e2e tests with [NightwatchJS](http://nightwatchjs.org).
10+
11+
Options:
12+
13+
```
14+
--url run e2e tests against given url instead of auto-starting dev server
15+
--config use custom nightwatch config file (overrides internals)
16+
-e, --env specify comma-delimited browser envs to run in (default: chrome)
17+
-t, --test specify a test to run by name
18+
-f, --filter glob to filter tests by filename
19+
```
20+
21+
> Note: this plugin currently uses Nightwatch v0.9.x. We are waiting for Nightwatch 1.0 to stabilize before upgrading.
22+
23+
Additionally, [all Nightwatch CLI options are also supported](https://github.com/nightwatchjs/nightwatch/blob/master/lib/runner/cli/cli.js).
24+
25+
## Configuration
26+
27+
We've pre-configured Nightwatch to run with Chrome by default. If you wish to run e2e tests in additional browsers, you will need to add a `nightwatch.config.js` or `nightwatch.json` in your project root to configure additional browsers. The config will be merged into the [internal Nightwatch config](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-plugin-e2e-nightwatch/nightwatch.config.js).
28+
29+
Alternatively, you can completely replace the internal config with a custom config file using the `--config` option.
30+
31+
Consult Nightwatch docs for [configuration options](http://nightwatchjs.org/gettingstarted#settings-file) and how to [setup browser drivers](http://nightwatchjs.org/gettingstarted#browser-drivers-setup).
32+
33+
## Installing in an Already Created Project
34+
35+
``` sh
36+
vue add @vue/e2e-nightwatch
37+
```

‎docs/core-plugins/eslint.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# @vue/cli-plugin-eslint
2+
3+
> eslint plugin for vue-cli
4+
5+
## Injected Commands
6+
7+
- **`vue-cli-service lint`**
8+
9+
```
10+
Usage: vue-cli-service lint [options] [...files]
11+
12+
Options:
13+
14+
--format [formatter] specify formatter (default: codeframe)
15+
--no-fix do not fix errors
16+
--max-errors specify number of errors to make build failed (default: 0)
17+
--max-warnings specify number of warnings to make build failed (default: Infinity)
18+
```
19+
20+
Lints and fixes files. If no specific files are given, it lints all files in `src` and `test`.
21+
22+
Other [ESLint CLI options](https://eslint.org/docs/user-guide/command-line-interface#options) are also supported.
23+
24+
## Configuration
25+
26+
ESLint can be configured via `.eslintrc` or the `eslintConfig` field in `package.json`.
27+
28+
Lint-on-save during development with `eslint-loader` is enabled by default. It can be disabled with the `lintOnSave` option in `vue.config.js`:
29+
30+
``` js
31+
module.exports = {
32+
lintOnSave: false
33+
}
34+
```
35+
36+
When set to `true`, `eslint-loader` will emit lint errors as warnings. By default, warnings are only logged to the terminal and does not fail the compilation.
37+
38+
To make lint errors show up in the browser overlay, you can use `lintOnSave: 'error'`. This will force `eslint-loader` to always emit errors. this also means lint errors will now cause the compilation to fail.
39+
40+
Alternatively, you can configure the overlay to display both warnings and errors:
41+
42+
``` js
43+
// vue.config.js
44+
module.exports = {
45+
devServer: {
46+
overlay: {
47+
warnings: true,
48+
errors: true
49+
}
50+
}
51+
}
52+
```
53+
54+
When `lintOnSave` is a truthy value, `eslint-loader` will be applied in both development and production. If you want to disable `eslint-loader` during production build, you can use the following config:
55+
56+
``` js
57+
// vue.config.js
58+
module.exports = {
59+
lintOnSave: process.env.NODE_ENV !== 'production'
60+
}
61+
```
62+
63+
## Installing in an Already Created Project
64+
65+
``` sh
66+
vue add @vue/eslint
67+
```
68+
69+
## Injected webpack-chain Rules
70+
71+
- `config.module.rule('eslint')`
72+
- `config.module.rule('eslint').use('eslint-loader')`

‎docs/core-plugins/pwa.md

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# @vue/cli-plugin-pwa
2+
3+
> pwa plugin for vue-cli
4+
5+
The service worker added with this plugin is only enabled in the production environment (e.g. only if you run `npm run build` or `yarn build`). Enabling service worker in a development mode is not a recommended practice, because it can lead to the situation when previously cached assets are used and the latest local changes are not included.
6+
7+
Instead, in the development mode the `noopServiceWorker.js` is included. This service worker file is effectively a 'no-op' that will reset any previous service worker registered for the same host:port combination.
8+
9+
If you need to test a service worker locally, build the application and run a simple HTTP-server from your build directory. It's recommended to use a browser incognito window to avoid complications with your browser cache.
10+
11+
## Configuration
12+
13+
Configuration is handled via the `pwa` property of either the `vue.config.js`
14+
file, or the `"vue"` field in `package.json`.
15+
16+
- **pwa.workboxPluginMode**
17+
18+
This allows you to the choose between the two modes supported by the underlying
19+
[`workbox-webpack-plugin`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin).
20+
21+
- `'GenerateSW'` (default), will lead to a new service worker file being created
22+
each time you rebuild your web app.
23+
24+
- `'InjectManifest'` allows you to start with an existing service worker file,
25+
and creates a copy of that file with a "precache manifest" injected into it.
26+
27+
The "[Which Plugin to Use?](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#which_plugin_to_use)"
28+
guide can help you choose between the two modes.
29+
30+
- **pwa.workboxOptions**
31+
32+
These options are passed on through to the underlying `workbox-webpack-plugin`.
33+
34+
For more information on what values are supported, please see the guide for
35+
[`GenerateSW`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#full_generatesw_config)
36+
or for [`InjectManifest`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#full_injectmanifest_config).
37+
38+
- **pwa.name**
39+
40+
- Default: "name" field in `package.json`
41+
42+
Used as the value for the `apple-mobile-web-app-title` meta tag in the generated HTML. Note you will need to edit `public/manifest.json` to match this.
43+
44+
- **pwa.themeColor**
45+
46+
- Default: `'#4DBA87'`
47+
48+
- **pwa.msTileColor**
49+
50+
- Default: `'#000000'`
51+
52+
- **pwa.appleMobileWebAppCapable**
53+
54+
- Default: `'no'`
55+
56+
This defaults to `'no'` because iOS before 11.3 does not have proper PWA support. See [this article](https://medium.com/@firt/dont-use-ios-web-app-meta-tag-irresponsibly-in-your-progressive-web-apps-85d70f4438cb) for more details.
57+
58+
- **pwa.appleMobileWebAppStatusBarStyle**
59+
60+
- Default: `'default'`
61+
62+
- **pwa.assetsVersion**
63+
64+
- Default: `''`
65+
66+
This option is used if you need to add a version to your icons and manifest, against browser’s cache. This will append `?v=<pwa.assetsVersion>` to the URLs of the icons and manifest.
67+
68+
- **pwa.manifestPath**
69+
70+
- Default: `'manifest.json'`
71+
72+
The path of app’s manifest.
73+
74+
- **pwa.manifestOptions**
75+
76+
- Default: `{}`
77+
78+
The object will be used to generate the `manifest.json`
79+
80+
If the following attributes are not defined in the object, the options of `pwa` or default options will be used instead.
81+
- name: `pwa.name`
82+
- short_name: `pwa.name`
83+
- start_url: `'.'`
84+
- display: `'standalone'`
85+
- theme_color: `pwa.themeColor`
86+
87+
- **pwa.iconPaths**
88+
89+
- Defaults:
90+
91+
```js
92+
{
93+
favicon32: 'img/icons/favicon-32x32.png',
94+
favicon16: 'img/icons/favicon-16x16.png',
95+
appleTouchIcon: 'img/icons/apple-touch-icon-152x152.png',
96+
maskIcon: 'img/icons/safari-pinned-tab.svg',
97+
msTileImage: 'img/icons/msapplication-icon-144x144.png'
98+
}
99+
```
100+
101+
Change these values to use different paths for your icons.
102+
103+
### Example Configuration
104+
105+
```js
106+
// Inside vue.config.js
107+
module.exports = {
108+
// ...other vue-cli plugin options...
109+
pwa: {
110+
name: 'My App',
111+
themeColor: '#4DBA87',
112+
msTileColor: '#000000',
113+
appleMobileWebAppCapable: 'yes',
114+
appleMobileWebAppStatusBarStyle: 'black',
115+
116+
// configure the workbox plugin
117+
workboxPluginMode: 'InjectManifest',
118+
workboxOptions: {
119+
// swSrc is required in InjectManifest mode.
120+
swSrc: 'dev/sw.js',
121+
// ...other Workbox options...
122+
}
123+
}
124+
}
125+
```
126+
127+
## Installing in an Already Created Project
128+
129+
``` sh
130+
vue add @vue/pwa
131+
```
132+
133+
## Injected webpack-chain Rules
134+
135+
- `config.plugin('workbox')`

0 commit comments

Comments
 (0)