mirror/vue-cli
1
0
Fork 0
mirror of https://github.com/vuejs/vue-cli.git synced 2026-03-06 06:18:38 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: wip

Browse Source
This commit is contained in:
Evan You
2018-06-07 23:20:51 -04:00
parent 999cbe4cde
commit 726aebdda5
6 changed files with 275 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
docs/config/README.md
View File

@@ -14,7 +14,7 @@ See the [Browser Compatibility](../guide/browser-compatibility.md#browserslist)
## vue.config.js
`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`).
`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.
The file should export an object containing options:
@@ -25,40 +25,190 @@ module.exports = {
}
```
::: tip
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.
:::
### baseUrl
- Type: `string`
- Default: `'/'`
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/'`.
Setting this value correctly is necessary for your static assets to be loaded properly in production.
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:
``` js
module.exports = {
baseUrl: process.env.NODE_ENV === 'production'
? '/production-sub-path/'
: '/'
}
```
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.
::: tip
Always use `baseUrl` instead of modifying webpack `output.publicPath`.
:::
### outputDir
- Type: `string`
- Default: `'dist'`
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).
::: tip
Always use `outputDir` instead of modifying webpack `output.path`.
:::
### assetsDir
- Type: `string`
- Default: `''`
A directory to nest generated static assets (js, css, img, fonts) under.
### pages
- Type: `Object`
- Default: `undefined`
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:
- An object that specifies its `entry`, `template` and `filename`;
- Or a string specifying its `entry`.
``` js
module.exports = {
pages: {
index: {
// entry for the page
entry: 'src/index/main.js',
// the source template
template: 'public/index.html',
// output as dist/index.html
filename: 'index.html'
},
// when using the entry-only string format,
// template is inferred to be `public/subpage.html`
// and falls back to `public/index.html` if not found.
// Output filename is inferred to be `subpage.html`.
subpage: 'src/subpage/main.js'
}
}
```
### lintOnSave
- Type: `boolean`
- Default: `true`
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.
### runtimeCompiler
- Type: `boolean`
- Default: `false`
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.
See also: [Runtime + Compiler vs. Runtime only](https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only).
### transpileDependencies
- Type: `Array<string | RegExp>`
- Default: `[]`
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.
### productionSourceMap
- Type: `boolean`
- Default: `true`
Setting this to `false` can speed up production builds if you don't need source maps for production.
### configureWebpack
- Type: `Object | Function`
If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge).
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.
See also: [Working with Webpack > Simple Configuration](../guide/webpack.md#simple-configuration)
### chainWebpack
- Type: `Function`
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.
See also: [Working with Webpack > Chaining](../guide/webpack.md#chaining-advanced)
### css.modules
- Type: `boolean`
- Default: `false`
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.
See also: [Working with CSS > CSS Modules](../guide/css.md#css-modules)
### css.extract
- Type: `boolean`
- Default: `true` (in production mode)
Whether to extract CSS in your components into a standalone CSS files (instead of inlined in JavaScript and injected dynamically).
This is also disabled by default when building as web components (styles are inlined and injected into shadowRoot).
When building as a library, you can also set this to `false` to avoid your users having to import the CSS themselves.
### css.sourceMap
- Type: `boolean`
- Default: `false`
Whether to enable source maps for CSS. Setting this to `true` may affect build performance.
### css.loaderOptions
- Type: `Object`
- Default: `{}`
Pass options to CSS-related loaders. For example:
``` js
module.exports = {
css: {
loaderOptions: {
css: {
// options here will be passed to css-loader
},
postcss: {
// options here will be passed to postcss-loader
}
}
}
}
```
Supported loaders are:
- [css-loader](https://github.com/webpack-contrib/css-loader)
- [postcss-loader](https://github.com/postcss/postcss-loader)
- [sass-loader](https://github.com/webpack-contrib/sass-loader)
- [less-loader](https://github.com/webpack-contrib/less-loader)
- [stylus-loader](https://github.com/shama/stylus-loader)
See also: [Passing Options to Pre-Processor Loaders](../guide/css.md#passing-options-to-pre-processor-loaders)
::: tip
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.
:::
### devServer
- Type: `Object`

2
docs/guide/README.md
View File

@@ -17,7 +17,7 @@ Vue CLI is a full system for rapid Vue.js development, providing:
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.
## Components
## Components of the System
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.

46
docs/guide/browser-compatibility.md
View File

@@ -2,14 +2,48 @@
## browserslist
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.
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.
See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
::: tip Note on Vendor-prefixed CSS Rules
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.
:::
See [here](browserslist) for how to specify browser ranges.
## Polyfills
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.
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.**
If one of your dependencies need polyfills, you have a few options:
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.
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.**
``` js
// babel.config.js
module.exports = {
presets: [
['@vue/app', {
polyfills: [
'es6.promise',
'es6.symbol'
]
}]
]
}
```
::: tip
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.
:::
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.
See [@babel-preset/env docs](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) for more details.
## Modern Mode
> TODO
[autoprefixer]: https://github.com/postcss/autoprefixer
[babel-preset-env]: https://new.babeljs.io/docs/en/next/babel-preset-env.html
[browserslist]: https://github.com/ai/browserslist

63
docs/guide/css.md
View File

@@ -2,14 +2,41 @@
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/).
## Pre-Processors
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:
``` bash
# Sass
npm install -D sass-loader node-sass
# Less
npm install -D less-loader less
# Stylus
npm install -D stylus-loader stylus
```
Then you can import the corresponding file types, or use them in `*.vue` files with:
``` vue
<style lang="scss">
$color = red;
</style>
```
## PostCSS
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).
Vue CLI uses PostCSS internally.
You can also configure `postcss-loader` via `css.loaderOptions.postcss` in `vue.config.js`.
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`.
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`.
::: tip Note on Vendor-prefixed CSS Rules
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.
:::
## CSS Modules
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'
import sassStyles from './foo.module.scss'
```
Alternatively, you can import a file explicitly with a `?module` resourceQuery so that you can drop the `.module` in the filename:
If you want to drop the `.module` in the filenames, set `css.modules` to `true` in `vue.config.js`:
``` js
import styles from './foo.css?module'
// works for all supported pre-processors as well
import sassStyles from './foo.scss?module'
// vue.config.js
module.exports = {
css: {
modules: true
}
}
```
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,6 +68,7 @@ module.exports = {
css: {
loaderOptions: {
css: {
localIdentName: '[name]-[hash]',
camelCase: 'only'
}
}
@@ -45,22 +76,6 @@ module.exports = {
}
```
## Pre-Processors
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:
``` bash
npm install -D sass-loader node-sass
```
Then you can import `.scss` files, or use it in `*.vue` files with:
``` vue
<style lang="scss">
$color = red;
</style>
```
## Passing Options to Pre-Processor Loaders
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:
- [less-loader](https://github.com/webpack-contrib/less-loader)
- [stylus-loader](https://github.com/shama/stylus-loader)
This is preferred over manually tapping into specific loaders, because these options will be shared across all rules that are related to it.
::: tip
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.
:::

46
docs/guide/html-and-static-assets.md
View File

@@ -1,17 +1,45 @@
# HTML and Static Assets
## Understanding `baseUrl`
## HTML
### The Index File
The file `public/index.html` is a template that will be processed with [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin). During build, asset links will be injected automatically. In addition, Vue CLI also automatically injects resource hints (`preload/prefetch`), manifest/icon links (when PWA plugin is used) and inlines the webpack runtime / chunk manifest for optimal performance.
The file `public/index.html` is a template that will be processed with [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin). During build, asset links will be injected automatically. In addition, Vue CLI also automatically injects resource hints (`preload/prefetch`), manifest/icon links (when PWA plugin is used), and the asset links for the JavaScript and CSS files produced during the build.
### Prefetch & Preload
### Interpolation
Since the index file is used as a template, you can use the [lodash template](https://lodash.com/docs/4.17.10#template) syntax to interpolate values in it. In addition to the [default values exposed by `html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates), all [client-side env variables](./mode-and-env.md#using-env-variables-in-client-side-code) are also available directly. For example, to use the `BASE_URL` value:
``` html
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
```
See also: [baseUrl](../config/#baseurl)
### Preload
[`<link rel="preload">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content) is a type of resource hint that is used to specify resources that your pages will need very soon after loading, which you therefore want to start preloading early in the lifecycle of a page load, before the browser's main rendering machinery kicks in.
By default, a Vue CLI app will automatically generate preload hints for all files that are needed for the initial rendering the your app.
The hints are injected using [@vue/preload-webpack-plugin](https://github.com/vuejs/preload-webpack-plugin) and can be modified / deleted via `chainWebpack` as `config.plugin('preload')`.
### Prefetch
[`<link rel="prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Link_prefetching_FAQ) is a type of resource hint that tells the browser to prefetch content that the user may visit in the near future in the browser's idle time, after the page finishes loading.
By default, a Vue CLI app will automatically generate prefetch hints for all JavaScript files generated for async chunks (as a result of [on-demand code splitting via dynamic `import()`](https://webpack.js.org/guides/code-splitting/#dynamic-imports)).
The hints are injected using [@vue/preload-webpack-plugin](https://github.com/vuejs/preload-webpack-plugin) and can be modified / deleted via `chainWebpack` as `config.plugin('prefetch')`.
::: tip
Prefetch links will consume bandwidth. If you have a large app with many async chunks and your user are primarily mobile and thus bandwidth-aware, you may want to disable prefetch links.
:::
### Building a Multi-Page App
Not every app has to be an SPA. Vue CLI supports building a multi-paged app using the [`pages` option in `vue.config.js`](../config/#pages). The built app will efficiently share common chunks between multiple entries for optimal loading performance.
## Static Assets Handling
Static assets can be handled in two different ways:
@@ -22,7 +50,7 @@ Static assets can be handled in two different ways:
### Relative Path Imports
When you reference a static asset using relative path inside JavaScript, CSS or `*.vue` files, the asset will be included into webpack's dependency graph. During this compilation process, all asset URLs such as `<img src="...">`, `background: url(...)` and CSS `@import` are **resolved as module dependencies**.
When you reference a static asset using relative path (must start with `.`) inside JavaScript, CSS or `*.vue` files, the asset will be included into webpack's dependency graph. During this compilation process, all asset URLs such as `<img src="...">`, `background: url(...)` and CSS `@import` are **resolved as module dependencies**.
For example, `url(./image.png)` will be translated into `require('./image.png')`, and
@@ -33,7 +61,7 @@ For example, `url(./image.png)` will be translated into `require('./image.png')`
will be compiled into:
``` js
createElement('img', { attrs: { src: require('./image.png') }})
h('img', { attrs: { src: require('./image.png') }})
```
Internally, we use `file-loader` to determine the final file location with version hashes and correct public base paths, and use `url-loader` to conditionally inline assets that are smaller than 10kb, reducing the amount of HTTP requests.
@@ -62,12 +90,12 @@ Note we recommended importing assets as part of your module dependency graph so
- Missing files cause compilation errors instead of 404 errors for your users.
- Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.
The `public` directory is provided as an **escape hatch**, and when you reference it via absolute path, you need to take into account where your app will be deployed. If your app is not deployed at the root of a domain, you will need to prefix your URLs with the base path:
The `public` directory is provided as an **escape hatch**, and when you reference it via absolute path, you need to take into account where your app will be deployed. If your app is not deployed at the root of a domain, you will need to prefix your URLs with the [baseUrl](../config/#baseurl):
- In `public/index.html`, you need to prefix the link with `<%= webpackConfig.output.publicPath %>`:
- In `public/index.html` or other HTML files used as templates by `html-webpack-plugin`, you need to prefix the link with `<%= BASE_URL %>`:
``` html
<link rel="shortcut icon" href="<%= webpackConfig.output.publicPath %>favicon.ico">
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
```
- In templates, you will need to first pass the base URL to your component:

4
packages/@vue/babel-preset-app/README.md
View File

@@ -4,7 +4,7 @@ This is the default Babel preset used in all Vue CLI projects.
## Included
- [babel-preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env)
- [@babel/preset-env](https://new.babeljs.io/docs/en/next/babel-preset-env.html)
- `modules: false`
- auto set to `'commonjs'` in Jest tests
- [`useBuiltIns: 'usage'`](#usebuiltins)
@@ -58,7 +58,7 @@ Note that the usage detection does not apply to your dependencies (which are exc
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.
See [babel-preset-env docs](https://github.com/babel/babel/tree/master/packages/babel-preset-env#usebuiltins) for more details.
See [@babel/preset-env docs](https://new.babeljs.io/docs/en/next/babel-preset-env.html#usebuiltins-usage) for more details.
### polyfills