docs: wip

Author: yyx990803

docs/.vuepress/config.js

@@ -3,7 +3,7 @@ module.exports = {
     '/': {
       lang: 'en-US',
       title: 'Vue CLI',
-      description: 'Standard Tooling for Vue.js Projects'
+      description: '🛠️ Standard Tooling for Vue.js Development'
     }
   },
   serviceWorker: true,

docs/.vuepress/override.styl

@@ -0,0 +1,2 @@
+.home .hero img
+  max-height 180px

docs/.vuepress/public/logo.png

@@ -1,30 +1,30 @@
-# Introduction
+---
+home: true
+heroImage: /logo.png
+actionText: Get Started →
+actionLink: /guide/
+features:
+- title: Feature Rich
+  details: Out-of-the-box support for Babel, TypeScript, ESLint, PostCSS, PWA, Unit Testing & End-to-end Testing.
+- title: Extensible
+  details: The plugin system allows the community to build and share reusable solutions to common needs.
+- title: No Need to Eject
+  details: Vue CLI is fully configurable without the need for ejecting. This allows your project to stay up-to-date for the long run.
+- title: GUI on top of the CLI
+  details: Create, develop and manage your projects through an accompanying graphical user interface.
+- title: Instant Prototyping
+  details: Instantly prototype new ideas with a single Vue file.
+- title: Future Ready
+  details: Effortlessly ship native ES2015 code for modern browsers, or build your vue components as native web components.
+footer: MIT Licensed | Copyright © 2018-present Evan You
+---
 
-Vue CLI is a full system for rapid Vue.js development, providing:
+## Getting Started
 
-- Interactive project scaffolding via `@vue/cli`.
-- Zero config rapid prototyping via `@vue/cli` + `@vue/cli-service-global`.
-- A runtime dependency (`@vue/cli-service`) that is:
-  - Upgradeable;
-  - Built on top of webpack, with sensible defaults;
-  - Configurable via in-project config file;
-  - Extensible via plugins
-- A rich collection of official plugins integrating the best tools in the frontend ecosystem.
+``` bash
+npm install -g @vue/cli
+# OR
+yarn global add @vue/cli
 
-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.
-
-- Overview
-- CLI
-  - Creating a Project
-  - Plugins and Presets
-  - Instant Prototyping
-  - CLI UI
-- Development
-  - The CLI Service
-  - Browser Compatibility
-  - HTML and static assets
-  - Mode and Environment Variables
-  - Git Hooks
-  - Building as a Library
-  - Building as Web Components
-  - Deployment
+vue create my-project
+```

docs/.vuepress/public/vue-cli-ui-preview.gif

@@ -50,6 +50,13 @@ module.exports = {
 
   // CSS related options
   css: {
+    //
+    // By defualt only files ending with *.modules.[ext] are loaded as
+    // CSS modules. Setting this to true enables CSS modules for all style
+    // file types.
+    // This option does not affect *.vue files.
+    modules: false,
+
     // extract CSS in components into a single CSS file (only in production)
     // can also be an object of options to pass to extract-text-webpack-plugin
     extract: true,
@@ -59,11 +66,13 @@ module.exports = {
 
     // pass custom options to pre-processor loaders. e.g. to pass options to
     // sass-loader, use { sass: { ... } }
-    loaderOptions: {},
-
-    // Enable CSS modules for all css / pre-processor files.
-    // This option does not affect *.vue files.
-    modules: false
+    loaderOptions: {
+      css: {},
+      postcss: {},
+      less: {},
+      sass: {},
+      stylus: {}
+    }
   },
 
   // use thread-loader for babel & TS in production build
@@ -113,6 +122,10 @@ module.exports = {
 
 The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
 
+::: warning
+Some webpack options are set based on values in `vue.config.js` and should not be mutated directly. For example, instead of modifying `output.path`, you should use the `outputDir` option in `vue.config.js`; instead of modifying `output.publicPath`, you should use the `baseUrl` option in `vue.config.js`. This is because the values in `vue.config.js` will be used in multiple places inside the config to ensure everything works properly together.
+:::
+
 If you need conditional behavior based on the environment, or want to directly mutate the config, use a function (which will be lazy evaluated after the env variables are set). The function receives the resolved config as the argument. Inside the function, you can either mutate the config directly, OR return an object which will be merged:
 
 ``` js
@@ -134,41 +147,29 @@ The internal webpack config is maintained using [webpack-chain](https://github.c
 
 This allows us finer-grained control over the internal config. Here are some examples:
 
-#### Transpiling a Dependency Module
-
-By default the Babel configuration skips
+#### Modifying Options of a Loader
 
 ``` js
 // vue.config.js
 module.exports = {
   chainWebpack: config => {
-    config.module
-      .rule('js')
-        .include
-          .add(/some-module-to-transpile/)
-  }
-}
-```
-
-#### Modifying Loader Options
-
-``` js
-// vue.config.js
-module.exports = {
-  chainWebpack: config => {
-    config.module
-      .rule('scss')
-      .use('sass-loader')
-      .tap(options =>
-        merge(options, {
-          includePaths: [path.resolve(__dirname, 'node_modules')],
+    config
+      .rule('vue')
+      .use('vue-loader')
+        .loader('vue-loader')
+        .tap(options => {
+          // modify the options...
+          return options
         })
-      )
   }
 }
 ```
 
-#### Adding a new loader example
+::: tip
+For CSS related loaders, it's recommended to use [css.loaderOptions](#passing-options-to-pre-processor-loaders) instead of directly targeting loaders via chaining. This is because there are multiple rules for each CSS file type and `css.loaderOptions` ensures you can affect all rules in one single place.
+:::
+
+#### Adding a New Loader
 
 ``` js
 // vue.config.js
@@ -185,23 +186,30 @@ module.exports = {
 }
 ```
 
-#### Replace existing Base Loader
+#### Replacing Loaders of a Rule
 
 If you want to replace an existing [Base Loader](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config/base.js), for example using `vue-svg-loader` to inline SVG files instead of loading the file:
 
 ``` js
 // vue.config.js
 module.exports = {
   chainWebpack: config => {
-    config.module
-      .rule('svg')
-      .use('file-loader')
+    const svgRule = config.module.rule('svg')
+
+    // clear all existing loaders.
+    // if you don't do this, the loader below will be appended to
+    // existing loaders of the rule.
+    svgRule.uses.clear()
+
+    // add replacement loader(s)
+    svgRule
+      .use('vue-svg-loader')
         .loader('vue-svg-loader')
   }
 }
 ```
 
-#### Modifying Plugin Options
+#### Modifying Options of a Plugin
 
 ``` js
 // vue.config.js
@@ -242,21 +250,37 @@ Since `@vue/cli-service` abstracts away the webpack config, it may be more diffi
 
 `vue-cli-service` exposes the `inspect` command for inspecting the resolved webpack config. The global `vue` binary also provides the `inspect` command, and it simply proxies to `vue-cli-service inspect` in your project.
 
-The command prints to stdout by default, so you can redirect that into a file for easier inspection:
+The command will print the resolved webpack config to stdout, which also contains hints on how to access rules and plugins via chaining.
+
+You can redirect the output into a file for easier inspection:
 
 ``` bash
 vue inspect > output.js
 ```
 
 Note the output is not a valid webpack config file, it's a serialized format only meant for inspection.
 
-You can also inspect a certain path of the config to narrow it down:
+You can also inspect a subset of the config by specifying a path:
 
 ``` bash
 # only inspect the first rule
 vue inspect module.rules.0
 ```
 
+Or, target a named rule or plugin:
+
+``` bash
+vue inspect --rule vue
+vue inspect --plugin html
+```
+
+Finally, you can list all named rules and plugins:
+
+``` bash
+vue inspect --rules
+vue inspect --plugins
+```
+
 ### Using Resolved Config as a File
 
 Some external tools may need access to the resolved webpack config as a file, for example IDEs or command line tools that expects a webpack config path. In that case you can use the following path:
@@ -275,6 +299,10 @@ Vue CLI projects comes with support for [PostCSS](http://postcss.org/), [CSS Mod
 
 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).
 
+You can also configure `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`.
+
 ### 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>`.
@@ -295,7 +323,20 @@ import styles from './foo.css?module'
 import sassStyles from './foo.scss?module'
 ```
 
-If you wish to customize the generated CSS modules class names, you can do so via the `css.localIdentName` option in `vue.config.js`.
+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`:
+
+``` js
+// vue.config.js
+module.exports = {
+  css: {
+    loaderOptions: {
+      css: {
+        camelCase: 'only'
+      }
+    }
+  }
+}
+```
 
 ### Pre-Processors
 
@@ -324,21 +365,26 @@ const fs = require('fs')
 module.exports = {
   css: {
     loaderOptions: {
+      // pass options to sass-loader
       sass: {
-        data: fs.readFileSync('src/variables.scss', 'utf-8')
+        // @/ is an alias to src/
+        // so this assumes you have a file named `src/variables.scss`
+        data: `@import "@/variables.scss";`
       }
     }
   }
 }
 ```
 
-This is preferred over manually tapping into specific loaders, because these options will be shared across all rules that are related to it.
+Loaders can be configured via `loaderOptions` include:
 
-## browserslist
+- [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)
 
-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.
-
-See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
+This is preferred over manually tapping into specific loaders, because these options will be shared across all rules that are related to it.
 
 ## Dev Server
 
@@ -401,10 +447,16 @@ module.exports = {
 
 ## Babel
 
-Babel can be configured via `.babelrc` or the `babel` field in `package.json`.
+Babel can be configured via `babel.config.js`.
+
+::: tip
+Vue CLI uses `babel.config.js` which is a new config format in Babel 7. Unlike `.babelrc` or the `babel` field in `package.json`, this config file does not use a file-location based resolution, and is applied consistently to any file under project root, including dependencies inside `node_modules`. It is recommended to always use `babel.config.js` instead of other formats in Vue CLI projects.
+:::
 
 All Vue CLI apps use `@vue/babel-preset-app`, which includes `babel-preset-env`, JSX support and optimized configuration for minimal bundle size overhead. See [its docs](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app) for details and preset options.
 
+Also see the [Polyfills](../guide/browser-compatibility.md#polyfills) section in guide.
+
 ## ESLint
 
 ESLint can be configured via `.eslintrc` or `eslintConfig` field in `package.json`.
@@ -436,3 +488,7 @@ See [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/pack
 ### Nightwatch
 
 See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
+
+## Browser Targets
+
+See the [Browser Compatibility](../guide/browser-compatibility.md#browserslist) section in guide.

docs/README.md

@@ -1,5 +1,5 @@
 ---
-sidebarDepth: 1
+sidebarDepth: 0
 ---
 
 # Overview
@@ -19,38 +19,30 @@ Vue CLI aims to be the standard tooling baseline for the Vue ecosystem. It ensur
 
 ## Understanding the Architecture
 
-### CLI
+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.
 
-The CLI is a installed globally npm package and provides the `vue` command in your terminal:
+### CLI
 
-``` bash
-npm install -g @vue/cli
-vue create my-project
-```
+The CLI (`@vue/cli`) is a globally installed npm package and provides the `vue` command in your terminal. It provides the ability to quickly scaffold a new project via `vue create`, or instantly prototype new ideas via `vue serve`. You can also manage your projects using a graphical user interface via `vue ui`. We will walk through what it can do in the next few sections of the guide.
 
 ### CLI Service
 
-`@vue/cli-service` is an npm package installed locally into every project created by `@vue/cli`. It contains the core service that loads other plugins, resolves the final webpack config, and provides the `vue-cli-service` binary to your project. If you are familiar with [create-react-app](https://github.com/facebookincubator/create-react-app), `@vue/cli-service` is essentially the equivalent of `react-scripts`, but more flexible.
-
-See [CLI Service docs](./cli-service.md) for all available commands.
+The CLI Service (`@vue/cli-service`) is a development dependency. It's an npm package installed locally into every project created by `@vue/cli`.
 
-### CLI Plugins
-
-Each project will likely contain a number of
+The CLI Service is built on top of [webpack](http://webpack.js.org/) and [webpack-dev-server](https://github.com/webpack/webpack-dev-server). It contains:
 
-### Presets
+- The core service that loads other CLI Plugins;
+- An internal webpack config that is optimized for most apps;
+- The `vue-cli-service` binary inside the project, which comes with the basic `serve`, `build` and `inspect` commands.
 
-A preset
+If you are familiar with [create-react-app](https://github.com/facebookincubator/create-react-app), `@vue/cli-service` is roughly the equivalent of `react-scripts`, although the feature set is different.
 
-## Development Features
+The section on [CLI Service](./cli-service.md) covers its detailed usage.
 
-- webpack
-- webpack-dev-server
-- pre-processors
-- git hooks
+### CLI Plugins
 
-## Configuration without Ejecting
+CLI Plugins are npm packages that provide optional features to your Vue CLI projects, such as Babel/TypeScript trasnpilation, ESLint integration, unit testing, and end-to-end testing. It's easy to spot a Vue CLI plugin as their names start with either `@vue/cli-plugin-` (for built-in plugins) or `vue-cli-plugin-` (for community plugins).
 
-Projects created from vue create are ready to go out-of-the-box. The plugins are designed to work with one another so in most cases, all you need to do is pick the features you want during the interactive prompts.
+When you run the `vue-cli-service` binary inside your project, it automatically resolves and loads all CLI Plugins listed in your project's `package.json`.
 
-However, we also understand that it's impossible to cater to every possible need, and the need of a project may also change over time. Projects created by Vue CLI allows you to configure almost every aspect of the tooling without ever needing to eject. Check out the [Config Reference](../config/) for more details.
+Plugins can be included as part of your project creation process or added into the project later. They can also be grouped into reusable presets. We will discuss these in more depth in the [Plugins and Presets](./plugins-and-presets.md) section.