Skip to content

Commit 8b79644

Browse files
yyx990803yyx990803
committed
docs: progress
1 parent 492adbd commit 8b79644

File tree

10 files changed

+301
-52
lines changed

10 files changed

+301
-52
lines changed

‎docs/README.md

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,20 @@
33
- [Introduction](#introduction)
44
- [CLI](#cli)
55
- [CLI Service](#cli-service)
6+
- [Conventions](#conventions)
7+
- [The Index Page](#the-index-page)
8+
- [Static Assets Handling](#static-assets-handling)
9+
- [Environment Variables and Modes](#environment-variables-and-modes)
610
- [Configuration](#configuration)
711
- [webpack](#webpack)
812
- [browserslist](#browserslist)
13+
- [Dev Server Proxy](#dev-server-proxy)
914
- [Babel](#babel)
1015
- [CSS](#css)
1116
- [ESLint](#eslint)
1217
- [TypeScript](#typescript)
1318
- [Unit Testing](#unit-testing)
1419
- [E2E Testing](#e2e-testing)
15-
- [Environment Variables and Modes](#environment-variables-and-modes)
1620
- [Development](#development)
1721

1822
## Introduction
@@ -39,34 +43,39 @@ npm install -g @vue/cli
3943
vue create my-project
4044
```
4145

42-
For full details on what the `vue` command can do, see the [full CLI docs](./cli.md).
46+
See [CLI docs](./cli.md) for all available commands.
4347

4448
## CLI Service
4549

4650
`@vue/cli-service` is a dependency 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.
4751

48-
Inside a project, you can access the binary directly as `vue-cli-service` in npm scripts, or as `./node_modules/.bin/vue-cli-service` from the terminal. This is what you will see in the `package.json` of a project using the default preset:
52+
See [CLI Service docs](./cli-service.md) for all available commands.
4953

50-
``` json
51-
{
52-
"scripts": {
53-
"serve": "vue-cli-service serve --open",
54-
"build": "vue-cli-service build"
55-
}
56-
}
57-
```
54+
## Conventions
5855

59-
Some CLI plugins will inject additional commands to `vue-cli-service`. For example, `@vue/cli-plugin-eslint` injects the `vue-cli-service lint` command. You can see all injected commands by running:
56+
### The Index Page
6057

61-
``` sh
62-
./node_modules/.bin/vue-cli-service help
63-
```
58+
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.
6459

65-
You can also learn about the available options of each command with:
60+
You can edit the file to add your own tags, but note one thing: you need to prefix links to assets with `<%= webpackConfig.output.publicPath %>` in case you are not deploying your app at the root of a domain.
6661

67-
``` sh
68-
./node_modules/.bin/vue-cli-service help [command]
69-
```
62+
### Static Assets Handling
63+
64+
Static assets can be handled in two different ways:
65+
66+
- Imported in JavaScript or referenced in templates/CSS via relative paths. Such references will be handled by webpack.
67+
68+
- Placed in the `public` directory and referenced via absolute paths. These assets will simply be copied and not go through webpack.
69+
70+
See [Static Assets Handling](./assets.md) for more details.
71+
72+
### Environment Variables and Modes
73+
74+
It is a common need to customize the app's behavior based on the target environment - for example, you may want the app to use different API endpoints or credentials during development / staging / production environments.
75+
76+
Vue CLI has comprehensive support for specifying different environment variables using modes and `.env` files.
77+
78+
See [Environment Variables and Modes](./env.md) for more details.
7079

7180
## Configuration
7281

@@ -101,6 +110,12 @@ You will notice a `browserlist` field in `package.json` specifying a range of br
101110

102111
See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
103112

113+
### Dev Server Proxy
114+
115+
If your frontend app and the backend API server are not running on the same host, you will need to proxy API requests to the API server during development. This is configurable via the `devServer.proxy` option in `vue.cofnig.js`.
116+
117+
See [Configuring Proxy](./cli-service.md#configuring-proxy) for more details.
118+
104119
### Babel
105120

106121
Babel can be configured via `.babelrc` or the `babel` field in `package.json`.
@@ -153,13 +168,7 @@ See [@vue/cli-plugin-typescript](https://github.com/vuejs/vue-cli/tree/dev/packa
153168

154169
See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
155170

156-
## Environment Variables and Modes
157-
158-
It is a common need to customize the app's behavior based on the target environment - for example, you may want the app to use different API endpoints or credentials during development / staging / production environments.
159-
160-
Vue CLI has comprehensive support for specifying different environment variables - see the [dedicated section](./env.md) for more details.
161-
162171
## Development
163172

164173
- [Contributing Guide](https://github.com/vuejs/vue-cli/blob/dev/.github/CONTRIBUTING.md)
165-
- [Plugin Development Guide](https://github.com/vuejs/vue-cli/blob/dev/docs/plugin.md).
174+
- [Plugin Development Guide](https://github.com/vuejs/vue-cli/blob/dev/docs/plugin.md)

‎docs/assets.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
## [TODO] Static Asset Handling

‎docs/build-targets.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## [TODO] Build Targets
2+
3+
### App
4+
5+
### Library
6+
7+
### Web Component

‎docs/cli-service.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
## CLI Service
2+
3+
- [Using the Binary](#using-the-binary)
4+
- [serve](#serve)
5+
- [Configuring Proxy](#configuring-proxy)
6+
- [build](#build)
7+
- [Caching and Parallel Mode](#caching-and-parallel-mode)
8+
- [Building as Library or Web Component](#building-as-library-or-web-component)
9+
- [DLL Mode](#dll-mode)
10+
- [inspect](#inspect)
11+
- [Checking All Available Commands](#checking-all-available-commands)
12+
13+
### Using the Binary
14+
15+
Inside a Vue CLI project, `@vue/cli-service` installs a binary named `vue-cli-service`. You can access the binary directly as `vue-cli-service` in npm scripts, or as `./node_modules/.bin/vue-cli-service` from the terminal.
16+
17+
This is what you will see in the `package.json` of a project using the default preset:
18+
19+
``` json
20+
{
21+
"scripts": {
22+
"serve": "vue-cli-service serve --open",
23+
"build": "vue-cli-service build"
24+
}
25+
}
26+
```
27+
28+
### serve
29+
30+
```
31+
Usage: vue-cli-service dev [options]
32+
33+
Options:
34+
35+
--open open browser on server start
36+
--mode specify env mode (default: development)
37+
--host specify host (default: 0.0.0.0)
38+
--port specify port (default: 8080)
39+
--https use https (default: false)
40+
```
41+
42+
`vue-cli-service serve` starts a dev server based on [webpack-dev-server](https://github.com/webpack/webpack-dev-server). It comes with hot-module-replacement (HMR) out of the box.
43+
44+
You can configure the dev server's behavior using the `devServer` option in `vue.config.js`:
45+
46+
``` js
47+
module.exports = {
48+
devServer: {
49+
open: process.platform === 'darwin',
50+
host: '0.0.0.0',
51+
port: 8080,
52+
https: false,
53+
hotOnly: false,
54+
proxy: null, // string | Object
55+
before: app => {
56+
// app is an express instance
57+
}
58+
}
59+
}
60+
```
61+
62+
#### Configuring Proxy
63+
64+
`devServer.proxy` can be a string pointing to the development API server:
65+
66+
``` js
67+
module.exports = {
68+
devServer: {
69+
proxy: 'http://localhost:4000'
70+
}
71+
}
72+
```
73+
74+
This will tell the dev server to proxy any unknown requests (requests that did not match a static file) to `http://localhost:4000`.
75+
76+
If you want to have more control over the proxy behavior, you can also use an object with `path: options` pairs. Consult [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware#proxycontext-config) for full options:
77+
78+
``` js
79+
module.exports = {
80+
devServer: {
81+
proxy: {
82+
'/api': {
83+
target: '<url>',
84+
ws: true
85+
},
86+
'/foo': {
87+
target: '<other_url>'
88+
}
89+
}
90+
}
91+
}
92+
```
93+
94+
### build
95+
96+
```
97+
Usage: vue-cli-service build [options] [entry|pattern]
98+
99+
Options:
100+
101+
--mode specify env mode (default: production)
102+
--dest specify output directory (default: dist)
103+
--target app | lib | wc | wc-async (default: app)
104+
--name name for lib or web-component mode (default: "name" in package.json or entry filename)
105+
```
106+
107+
`vue-cli-service build` produces a production-ready bundle in the `dist/` directory, with minification for JS/CSS/HTML and auto vendor chunk splitting for better caching. The chunk manifest is inlined into the HTML.
108+
109+
#### Caching and Parallel Mode
110+
111+
- `cache-laoder` is enabled for Babel/TypeScript transpilation by default.
112+
- `thread-loader` will be enabled for Babel/TypeScript transpilation when the machine has more than 1 CPI cores.
113+
114+
#### Building as Library or Web Components
115+
116+
It is also possible to build any component(s) inside your project as a library or as web components. See [Build Targets](./build-targets.md) for more details.
117+
118+
#### DLL Mode
119+
120+
If your app has a large amount of dependency libraries, you can improve the build performance by opting into DLL mode. DLL mode builds your dependencies into a separate vendor bundle which will be reused on future builds as long as your dependencies did not change.
121+
122+
To enable DLL mode, set the `dll` option in `vue.config.js` to `true`:
123+
124+
``` js
125+
// vue.config.js
126+
module.exports = {
127+
dll: true
128+
}
129+
```
130+
131+
This by default builds **all the modules listed in the `dependencies` field in `package.json`** into the DLL bundle. It is important that you correctly list your dependencies, otherwise it may end up including unnecessary code.
132+
133+
If you wish to have finer grained control over what modules to be included in the DLL bundle, you can also provide an Array of modules to the `dll` option:
134+
135+
``` js
136+
// vue.config.js
137+
module.exports = {
138+
dll: [
139+
'dep-a',
140+
'dep-b/some/nested/file.js'
141+
]
142+
}
143+
```
144+
145+
### inspect
146+
147+
```
148+
Usage: vue-cli-service inspect [options] [...paths]
149+
150+
Options:
151+
152+
--mode specify env mode (default: development)
153+
```
154+
155+
You can use `vue-cli-service inspect` to inspect the webpack config inside a Vue CLI project. See [Inspecting Webpack Config](./webpack.md#inspecting-the-projects-webpack-config) for more details.
156+
157+
### Checking All Available Commands
158+
159+
Some CLI plugins will inject additional commands to `vue-cli-service`. For example, `@vue/cli-plugin-eslint` injects the `vue-cli-service lint` command. You can see all injected commands by running:
160+
161+
``` sh
162+
./node_modules/.bin/vue-cli-service help
163+
```
164+
165+
You can also learn about the available options of each command with:
166+
167+
``` sh
168+
./node_modules/.bin/vue-cli-service help [command]
169+
```

0 commit comments

Comments
 (0)