salvage docs (vuejs#603)

kazupon · egoist · commit 511bd11fdb5c · 2017-10-08T21:47:35.000-05:00
diff --git a/docs/build.md b/docs/build.md
@@ -0,0 +1,298 @@
+# vue build
+
+`vue build` command gives you a zero-configuration development setup, install once and build everywhere.
+
+## Features
+
+- **Not a boilerplate**: run a single command to develop your app
+- **Out of the box**: ES2015, single-file component with hot reloading and custom CSS preprocessors
+- **Customizable**: populate a `~/.vue/webpack.config.js` for custom webpack config
+- **Single-file component mode**: simply run `vue build Component.vue` and test it out in the browser!
+
+## Get started
+
+Make sure that you've installed `vue-cli` with `npm >= 3` or `yarn >= 0.7`.
+
+Populate an app entry `./index.js` in your project:
+
+```js
+import Vue from 'vue'
+
+new Vue({
+  el: '#app',
+  render: h => h('h2', 'hello world')
+})
+```
+
+And then run `vue build index.js` and go to `http://localhost:4000`
+
+**To build for production (minimized and optimized):**
+
+```bash
+$ vue build index.js --prod
+```
+
+If you want to directly test a component without manually create a Vue instance for it, try:
+
+```bash
+$ vue build Component.vue
+```
+
+<details><summary>How does this work?</summary><br>
+When the input file ends with `.vue` extension, we use a [default app entry](/lib/default-entry.es6) to load the given component, otherwise we treat it as a normal webpack entry. For jsx component which ends with `.js` extension, you can enable this behavior manually by adding `--mount`.
+</details>
+
+**To distribute component:**
+
+```bash
+$ vue build Component.vue --prod --lib
+```
+
+This will create an optimized bundle in UMD format, and the name of exported library is set to `Component`, you can use `--lib [CustomLibraryName]` to customize it.
+
+Note that in some cases you may use [`externals`](https://webpack.js.org/configuration/externals/) to exclude some modules from your bundle.
+
+**Watch mode:**
+
+```bash
+$ vue build index.js --watch
+```
+
+It's similar to `development mode` but does not add hot-reloading support and uses a real file system.
+
+**For more CLI usages:**
+
+```bash
+$ vue build -h
+```
+
+## Configuration files
+
+By default, we use `~/.vue/config.js` and `~/.vue/webpack.config.js` if they exist.
+
+To use a custom config file, add `--config [file]`
+
+To use a custom webpack config file, add `--webpack [file]`
+
+### config.js
+
+You can define CLI options in this file.
+
+#### entry
+
+Type: `string` `Array` `Object`
+
+It's the first argument of `vue build` command, eg: `vue build entry.js`. You can set it here to omit it in CLI arguments.
+
+The single-component mode (`--mount`) will not work if you set `entry` to an `Array` or `Object`.
+
+- `Array`: Override `webpackConfig.entry.client`
+- `Object`: Override `webpackConfig.entry`
+- `string`: Added to `webpackConfig.entry.client` or used as `webpackConfig.resolve.alias['your-tasteful-component']` in single-component mode.
+
+#### port
+
+Type: `number`<br>
+Default: `4000`
+
+Port of dev server.
+
+#### webpack
+
+Type: `function` `string` `object`
+
+##### function
+
+`webpack(webpackConfig, options, webpack)`
+
+- webpackConfig: current webpack config
+- options: CLI options (assigned with config.js)
+- webpack: The `webpack` module
+
+Return a new webpack config.
+
+##### string
+
+Used as the path to webpack config file, eg: `--webpack webpack.config.js`
+
+##### object
+
+Directly use as webpack config.
+
+Note that we use [webpack-merge](https://github.com/survivejs/webpack-merge) to merge your webpack config with default webpack config.
+
+#### autoprefixer
+
+Type: `object`
+
+Autoprefixer options, default value:
+
+```js
+{
+  browsers: ['ie > 8', 'last 5 versions']
+}
+```
+
+#### postcss
+
+Type: `Object` `Array` `Function`
+
+PostCSS options, if it's an `Array` or `Function`, the default value will be override:
+
+```js
+{
+  plugins: [
+    require('autoprefixer')(options.autoprefixer)
+  ]
+}
+```
+
+#### babel
+
+Type: `Object`
+
+[Babel options](https://github.com/babel/babel-loader#options). You can set `babel.babelrc` to false to disable using `.babelrc`.
+
+#### html
+
+Type: `Object` `Array` `boolean`
+
+[html-webpack-plugin](https://github.com/ampedandwired/html-webpack-plugin) options, use this option to customize `index.html` output, default value:
+
+```js
+{
+  title: 'Vue App',
+  template: path.join(__dirname, '../lib/template.html')
+}
+```
+
+Check out the [default template](/lib/template.html) file we use. To disable generating html file, you can set `html` to `false`.
+
+#### filename
+
+Set custom filename for `js` `css` `static` files:
+
+```js
+{
+  filename: {
+    js: 'index.js',
+    css: 'style.css',
+    static: 'static/[name].[ext]'  
+  }
+}
+```
+
+#### disableCompress
+
+Type: `boolean`
+
+In production mode, all generated files will be compressed and produce sourcemaps file. You can use `--disableCompress` to disable this behavior.
+
+#### hmrEntries
+
+Type: `Array`<br>
+Default: `['client']`
+
+Add `webpack-hot-middleware` HMR client to specific webpack entries. By default your app is loaded in `client` entry, so we insert it here.
+
+#### proxy
+
+Type: `string`, `Object`
+
+To tell the development server to serve any `/api/*` request to your API server in development, use the `proxy` options:
+
+```js
+module.exports = {
+  proxy: 'http://localhost:8080/api'
+}
+```
+
+This way, when you fetch `/api/todos` in your Vue app, the development server will proxy your request to `http://localhost:8080/api/todos`.
+
+We use [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) under the hood, so the `proxy` option can also be an object:
+
+```js
+module.exports = {
+  proxy: {
+    '/api/foo': 'http://localhost:8080/api',
+    '/api/fake-data': {
+      target: 'http://jsonplaceholder.typicode.com',
+      changeOrigin: true,
+      pathRewrite: {
+        '^/api/fake-data': ''
+      }
+    }
+  }
+}
+```
+
+Keep in mind that proxy only has effect in development.
+
+#### setup
+
+Type: `function`
+
+Perform some custom logic to development server:
+
+```js
+module.exports = {
+  setup(app) {
+    app.get('/api', (req, res) => {
+      res.end('This is the API')
+    })
+  }
+}
+```
+
+#### run(webpackConfig, options)
+
+Type: `function`
+
+You can use a custom `run` function to perform your own build process instead of the default one. For example, run karma with the processed webpack config:
+
+```js
+const Server = require('karma').Server
+
+module.exports = {
+  run(webpackConfig) {
+    const server = new Server({
+      webpack: webpackConfig,
+      // other karma options...
+    }, exitCode => {
+      console.log('Karma has exited with ' + exitCode)
+      process.exit(exitCode)
+    })
+    server.start()
+  }
+}
+```
+
+### webpack.config.js
+
+All the webpack options are available here.
+
+## Recipes
+
+### Custom CSS preprocessors
+
+CSS preprocessors (and CSS extraction) work out of the box, install relevant loaders and you're all set! For example, add `sass` support:
+
+```bash
+$ npm i -D node-sass sass-loader
+```
+
+Since all CSS will be piped through `postcss-loader`, `autoprefixer` and `postcss` options will always work no matter what CSS preprocessors you're using.
+
+### Custom babel config
+
+By default we only use a single babel preset: [babel-preset-vue-app](https://github.com/egoist/babel-preset-vue-app) which includes following features:
+
+- ES2015/2016/2017 and Stage-2 features
+- Transform `async/await` and `generator`
+- Transform Vue JSX
+
+You can set `babel` option in config file or populate a `.babelrc` in project root directory to override it.
+
+### Copy static files
+
+Everything in `./static` folder will be copied to dist folder, for example: `static/favicon.ico` will be copied to `dist/favicon.ico`.
