Skip to content

Commit 726aebd

Browse files
yyx990803yyx990803
committed
docs: wip
1 parent 999cbe4 commit 726aebd

File tree

6 files changed

+275
-46
lines changed

6 files changed

+275
-46
lines changed

‎docs/config/README.md

+155-5
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ See the [Browser Compatibility](../guide/browser-compatibility.md#browserslist)
1414

1515
## vue.config.js
1616

17-
`vue.config.js` is an optional config file that will be automatically loaded by `@vue/cli-service` if it's present in your project root (next to `package.json`).
17+
`vue.config.js` is an optional config file that will be automatically loaded by `@vue/cli-service` if it's present in your project root (next to `package.json`). You can also use the `vue` field in `package.json`, but do note in that case you will be limited to JSON-compatible values only.
1818

1919
The file should export an object containing options:
2020

@@ -25,40 +25,190 @@ module.exports = {
2525
}
2626
```
2727

28-
::: tip
29-
You can also use the `vue` field in `package.json`, but do note in that case you will be limited to JSON-compatible values only.
30-
:::
31-
3228
### baseUrl
3329

30+
- Type: `string`
31+
- Default: `'/'`
32+
33+
The base URL your application will be deployed at. By default Vue CLI assumes your app will be deployed at the root of a domain, e.g. `https://www.my-app.com/`. If your app is deployed at a sub-path, you will need to specify that sub-path using this option. For example, if your app is deployed at `https://www.foobar.com/my-app/`, set `baseUrl` to `'/my-app/'`.
34+
35+
Setting this value correctly is necessary for your static assets to be loaded properly in production.
36+
37+
This value is also respected during development. If you want your dev server to be served at root instead, you can use a conditional value:
38+
39+
``` js
40+
module.exports = {
41+
baseUrl: process.env.NODE_ENV === 'production'
42+
? '/production-sub-path/'
43+
: '/'
44+
}
45+
```
46+
47+
The value can also be set to an empty string (`''`) so that all assets are linked using relative paths, so that the bundle can be used in a file system based environment like a Cordova hybrid app. The caveat is that this will force the generated CSS files to always be placed at the root of the output directory to ensure urls in your CSS work correctly.
48+
49+
::: tip
50+
Always use `baseUrl` instead of modifying webpack `output.publicPath`.
51+
:::
52+
3453
### outputDir
3554

55+
- Type: `string`
56+
- Default: `'dist'`
57+
58+
The directory where the production build files will be generated in when running `vue-cli-service build`. Note the target directory will be removed before building (this behavior can be disabled by passing `--no-clean` when building).
59+
60+
::: tip
61+
Always use `outputDir` instead of modifying webpack `output.path`.
62+
:::
63+
3664
### assetsDir
3765

66+
- Type: `string`
67+
- Default: `''`
68+
69+
A directory to nest generated static assets (js, css, img, fonts) under.
70+
71+
### pages
72+
73+
- Type: `Object`
74+
- Default: `undefined`
75+
76+
Build the app in multi-page mode. Each "page" should have a corresponding JavaScript entry file. The value should be an object where the key is the name of the entry, and the value is either:
77+
78+
- An object that specifies its `entry`, `template` and `filename`;
79+
- Or a string specifying its `entry`.
80+
81+
``` js
82+
module.exports = {
83+
pages: {
84+
index: {
85+
// entry for the page
86+
entry: 'src/index/main.js',
87+
// the source template
88+
template: 'public/index.html',
89+
// output as dist/index.html
90+
filename: 'index.html'
91+
},
92+
// when using the entry-only string format,
93+
// template is inferred to be `public/subpage.html`
94+
// and falls back to `public/index.html` if not found.
95+
// Output filename is inferred to be `subpage.html`.
96+
subpage: 'src/subpage/main.js'
97+
}
98+
}
99+
```
100+
38101
### lintOnSave
39102

103+
- Type: `boolean`
104+
- Default: `true`
105+
106+
Whether to perform lint-on-save during development using [eslint-loader](https://github.com/webpack-contrib/eslint-loader). This value is respected only when [`@vue/cli-plugin-eslint`](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint) is installed.
107+
40108
### runtimeCompiler
41109

110+
- Type: `boolean`
111+
- Default: `false`
112+
113+
Whether to use the build of Vue core that includes the runtime compiler. Setting it to `true` will allow you to use the `template` option in Vue components, but will incur around an extra 10kb payload for your app.
114+
115+
See also: [Runtime + Compiler vs. Runtime only](https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only).
116+
42117
### transpileDependencies
43118

119+
- Type: `Array<string | RegExp>`
120+
- Default: `[]`
121+
122+
By default `babel-loader` ignores all files inside `node_modules`. If you want to explicitly trasnpile a dependency with Babel, you can list it in this option.
123+
44124
### productionSourceMap
45125

126+
- Type: `boolean`
127+
- Default: `true`
128+
129+
Setting this to `false` can speed up production builds if you don't need source maps for production.
130+
46131
### configureWebpack
47132

48133
- Type: `Object | Function`
49134

135+
If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge).
136+
137+
If the value is a function, it will receive the resolved config as the argument. The function can either mutate the config and return nothing, OR return a cloned or merged version of the config.
138+
139+
See also: [Working with Webpack > Simple Configuration](../guide/webpack.md#simple-configuration)
140+
50141
### chainWebpack
51142

52143
- Type: `Function`
53144

145+
A function that will receive an instance of `ChainableConfig` powered by [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). Allows for more fine-grained modification of the internal webpack config.
146+
147+
See also: [Working with Webpack > Chaining](../guide/webpack.md#chaining-advanced)
148+
54149
### css.modules
55150

151+
- Type: `boolean`
152+
- Default: `false`
153+
154+
By default, only files that ends in `*.module.[ext]` are treated as CSS modules. Setting this to `true` will allow you to drop `.module` in the filenames and treat all `*.(css|scss|sass|less|styl(us)?)` files as CSS modules.
155+
156+
See also: [Working with CSS > CSS Modules](../guide/css.md#css-modules)
157+
56158
### css.extract
57159

160+
- Type: `boolean`
161+
- Default: `true` (in production mode)
162+
163+
Whether to extract CSS in your components into a standalone CSS files (instead of inlined in JavaScript and injected dynamically).
164+
165+
This is also disabled by default when building as web components (styles are inlined and injected into shadowRoot).
166+
167+
When building as a library, you can also set this to `false` to avoid your users having to import the CSS themselves.
168+
58169
### css.sourceMap
59170

171+
- Type: `boolean`
172+
- Default: `false`
173+
174+
Whether to enable source maps for CSS. Setting this to `true` may affect build performance.
175+
60176
### css.loaderOptions
61177

178+
- Type: `Object`
179+
- Default: `{}`
180+
181+
Pass options to CSS-related loaders. For example:
182+
183+
``` js
184+
module.exports = {
185+
css: {
186+
loaderOptions: {
187+
css: {
188+
// options here will be passed to css-loader
189+
},
190+
postcss: {
191+
// options here will be passed to postcss-loader
192+
}
193+
}
194+
}
195+
}
196+
```
197+
198+
Supported loaders are:
199+
200+
- [css-loader](https://github.com/webpack-contrib/css-loader)
201+
- [postcss-loader](https://github.com/postcss/postcss-loader)
202+
- [sass-loader](https://github.com/webpack-contrib/sass-loader)
203+
- [less-loader](https://github.com/webpack-contrib/less-loader)
204+
- [stylus-loader](https://github.com/shama/stylus-loader)
205+
206+
See also: [Passing Options to Pre-Processor Loaders](../guide/css.md#passing-options-to-pre-processor-loaders)
207+
208+
::: tip
209+
This is preferred over manually tapping into specific loaders using `chainWebpack`, because these options need to be applied in multiple locations where the corresponding loader is used.
210+
:::
211+
62212
### devServer
63213

64214
- Type: `Object`

‎docs/guide/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Vue CLI is a full system for rapid Vue.js development, providing:
1717

1818
Vue CLI aims to be the standard tooling baseline for the Vue ecosystem. It ensures the various build tools work smoothly together with sensible defaults so you can focus on writing your app instead of spending days wrangling with configurations. At the same time, it still offers the flexibility to tweak the config of each tool without the need for ejecting.
1919

20-
## Components
20+
## Components of the System
2121

2222
There are several moving parts of Vue CLI - if you look at the [source code](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue), you will find that it is a monorepo containing a number of separately published packages.
2323

‎docs/guide/browser-compatibility.md

+40-6
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,48 @@
22

33
## browserslist
44

5-
You will notice a `browserslist` field in `package.json` specifying a range of browsers the project is targeting. This value will be used by `babel-preset-env` and `autoprefixer` to automatically determine the JavaScript polyfills and CSS vendor prefixes needed.
5+
You will notice a `browserslist` field in `package.json` specifying a range of browsers the project is targeting. This value will be used by [@babel/preset-env][babel-preset-env] and [autoprefixer][autoprefixer] to automatically determine the JavaScript features that need to be transpiled and the CSS vendor prefixes needed.
66

7-
See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
8-
9-
::: tip Note on Vendor-prefixed CSS Rules
10-
In the production build, Vue CLI optimizes your CSS and will drop unnecessary vendor-prefixed CSS rules based on your browser targets. With [autoprefixer](https://github.com/postcss/autoprefixer) enabled by default, you should always use only non-prefixed CSS rules.
11-
:::
7+
See [here](browserslist) for how to specify browser ranges.
128

139
## Polyfills
1410

11+
A default Vue CLI project uses [@vue/babel-preset-app][babel-preset-env], which uses `@babel/preset-env` and the `browserslist` config to determine the Polyfills needed for your project.
12+
13+
By default, it passes [`useBuiltIns: 'usage'`](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) to `@babel/preset-env` which automatically detects the polyfills needed based on the language features used in your source code. This ensures only the minimum amount of polyfills are included in your final bundle. However, this also means **if one of your dependencies has specific requirements on polyfills, by default Babel won't be able to detect it.**
14+
15+
If one of your dependencies need polyfills, you have a few options:
16+
17+
1. **If the dependency is written in an ES version that your target environments do not support:** Add that dependency to the [`transpileDependencies`](../config/#transpiledependencies) option in `vue.config.js`. This would enable both syntax transforms and usage-based polyfill detection for that dependency.
18+
19+
2. **If the dependency ships ES5 code and explicitly lists the polyfills needed:** you can pre-include the needed polyfills using the [polyfills](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app#polyfills) option for `@vue/babel-preset-app`. **Note that `es6.promise` is included by default because it's very common for libs to depend on Promises.**
20+
21+
``` js
22+
// babel.config.js
23+
module.exports = {
24+
presets: [
25+
['@vue/app', {
26+
polyfills: [
27+
'es6.promise',
28+
'es6.symbol'
29+
]
30+
}]
31+
]
32+
}
33+
```
34+
35+
::: tip
36+
It's recommended to add polyfills this way instead of directly importing them in your source code, because polyfills listed here can be automatically excluded if your `browserslist` targets don't need them.
37+
:::
38+
39+
3. **If the dependency ships ES5 code, but uses ES6+ features without explicitly listing polyfill requirements (e.g. Vuetify):** Use `useBuiltIns: 'entry'` and then add `import '@babel/polyfill'` to your entry file. This will import **ALL** polyfills based on your `browserslist` targets so that you don't need to worry about dependency polyfills anymore, but will likely increase your final bundle size with some unused polyfills.
40+
41+
See [@babel-preset/env docs](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) for more details.
42+
1543
## Modern Mode
44+
45+
> TODO
46+
47+
[autoprefixer]: https://github.com/postcss/autoprefixer
48+
[babel-preset-env]: https://new.babeljs.io/docs/en/next/babel-preset-env.html
49+
[browserslist]: https://github.com/ai/browserslist

‎docs/guide/css.md

+40-23
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,41 @@
22

33
Vue CLI projects comes with support for [PostCSS](http://postcss.org/), [CSS Modules](https://github.com/css-modules/css-modules) and pre-processors including [Sass](https://sass-lang.com/), [Less](http://lesscss.org/) and [Stylus](http://stylus-lang.com/).
44

5+
## Pre-Processors
6+
7+
You can select pre-processors (Sass/Less/Stylus) when creating the project. If you did not do so, the internal webpack config is still pre-configured to handle all of them. You just need to manually install the corresponding webpack loaders:
8+
9+
``` bash
10+
# Sass
11+
npm install -D sass-loader node-sass
12+
13+
# Less
14+
npm install -D less-loader less
15+
16+
# Stylus
17+
npm install -D stylus-loader stylus
18+
```
19+
20+
Then you can import the corresponding file types, or use them in `*.vue` files with:
21+
22+
``` vue
23+
<style lang="scss">
24+
$color = red;
25+
</style>
26+
```
27+
528
## PostCSS
629

7-
Vue CLI uses PostCSS internally, and enables [autoprefixer](https://github.com/postcss/autoprefixer) by default. You can configure PostCSS via `.postcssrc` or any config source supported by [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config).
30+
Vue CLI uses PostCSS internally.
831

9-
You can also configure `postcss-loader` via `css.loaderOptions.postcss` in `vue.config.js`.
32+
You can configure PostCSS via `.postcssrc` or any config source supported by [postcss-load-config](https://github.com/michael-ciniawsky/postcss-load-config), and configure [postcss-loader](https://github.com/postcss/postcss-loader) via `css.loaderOptions.postcss` in `vue.config.js`.
1033

1134
The [autoprefixer](https://github.com/postcss/autoprefixer) plugin is enabled by default. To configure the browser targets, use the [browserslist](../guide/browser-compatibility.html#browserslist) field in `package.json`.
1235

36+
::: tip Note on Vendor-prefixed CSS Rules
37+
In the production build, Vue CLI optimizes your CSS and will drop unnecessary vendor-prefixed CSS rules based on your browser targets. With `autoprefixer` enabled by default, you should always use only non-prefixed CSS rules.
38+
:::
39+
1340
## CSS Modules
1441

1542
You can [use CSS Modules in `*.vue` files](https://vue-loader.vuejs.org/en/features/css-modules.html) out of the box with `<style module>`.
@@ -22,12 +49,15 @@ import styles from './foo.module.css'
2249
import sassStyles from './foo.module.scss'
2350
```
2451

25-
Alternatively, you can import a file explicitly with a `?module` resourceQuery so that you can drop the `.module` in the filename:
52+
If you want to drop the `.module` in the filenames, set `css.modules` to `true` in `vue.config.js`:
2653

2754
``` js
28-
import styles from './foo.css?module'
29-
// works for all supported pre-processors as well
30-
import sassStyles from './foo.scss?module'
55+
// vue.config.js
56+
module.exports = {
57+
css: {
58+
modules: true
59+
}
60+
}
3161
```
3262

3363
If you wish to customize the generated CSS modules class names, you can do so via `css.loaderOptions.css` in `vue.config.js`. All `css-loader` options are supported here, for example `localIdentName` and `camelCase`:
@@ -38,29 +68,14 @@ module.exports = {
3868
css: {
3969
loaderOptions: {
4070
css: {
71+
localIdentName: '[name]-[hash]',
4172
camelCase: 'only'
4273
}
4374
}
4475
}
4576
}
4677
```
4778

48-
## Pre-Processors
49-
50-
You can select pre-processors (Sass/Less/Stylus) when creating the project. If you did not do so, you can also just manually install the corresponding webpack loaders. The loaders are pre-configured and will automatically be picked up. For example, to add Sass to an existing project, simply run:
51-
52-
``` bash
53-
npm install -D sass-loader node-sass
54-
```
55-
56-
Then you can import `.scss` files, or use it in `*.vue` files with:
57-
58-
``` vue
59-
<style lang="scss">
60-
$color = red;
61-
</style>
62-
```
63-
6479
## Passing Options to Pre-Processor Loaders
6580

6681
Sometimes you may want to pass options to the pre-processor's webpack loader. You can do that using the `css.loaderOptions` option in `vue.config.js`. For example, to pass some shared global variables to all your Sass styles:
@@ -91,4 +106,6 @@ Loaders can be configured via `loaderOptions` include:
91106
- [less-loader](https://github.com/webpack-contrib/less-loader)
92107
- [stylus-loader](https://github.com/shama/stylus-loader)
93108

94-
This is preferred over manually tapping into specific loaders, because these options will be shared across all rules that are related to it.
109+
::: tip
110+
This is preferred over manually tapping into specific loaders using `chainWebpack`, because these options need to be applied in multiple locations where the corresponding loader is used.
111+
:::

0 commit comments

Comments
 (0)