docs: wip

tiwuofficial · Jun 8, 2018 · 726aebd · 726aebd
1 parent 999cbe4
commit 726aebd
Show file tree

Hide file tree

Showing 6 changed files with 275 additions and 46 deletions.
diff --git a/docs/config/README.md b/docs/config/README.md
@@ -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`

diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -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.
 

diff --git a/docs/guide/browser-compatibility.md b/docs/guide/browser-compatibility.md
@@ -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
diff --git a/docs/guide/css.md b/docs/guide/css.md
@@ -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,29 +68,14 @@ module.exports = {
   css: {
     loaderOptions: {
       css: {
+        localIdentName: '[name]-[hash]',
         camelCase: 'only'
       }
     }
   }
 }
 ```
 
-## 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.
+:::