mirror of
https://github.com/vuejs/vue-cli.git
synced 2026-04-26 06:48:16 -05:00
docs: wip
This commit is contained in:
Evan You
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
+40
-23
@@ -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.
|
||||
:::
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user