8000 docs: initial docs · atinux/vue-cli@dfb2583 · GitHub
[go: up one dir, main page]
Skip to content

Commit dfb2583

Browse files
yyx990803yyx990803
committed
docs: initial docs
1 parent dd04add commit dfb2583

File tree

7 files changed

+300
-20
lines changed

7 files changed

+300
-20
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,4 +52,4 @@ Note that `jest --onlyChanged` isn't always accurate because some tests spawn ch
5252

5353
### Plugin Development
5454

55-
See [dedicated section in docs](https://github.com/vuejs/vue-cli/tree/dev/docs/Plugin.md).
55+
See [dedicated section in docs](https://github.com/vuejs/vue-cli/tree/dev/docs/plugin.md).

‎docs/README.md

Lines changed: 106 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,142 @@
1-
# WIP
1+
## Table of Contents
2+
3+
- [Introduction](#introduction)
4+
- [CLI](#cli)
5+
- [CLI Service](#cli-service)
6+
- [Configuration](#configuration)
7+
- [webpack](#webpack)
8+
- [browserslist](#browserslist)
9+
- [Babel](#babel)
10+
- [CSS](#css)
11+
- [ESLint](#eslint)
12+
- [TypeScript](#typescript)
13+
- [Unit Testing](#unit-testing)
14+
- [E2E Testing](#e2e-testing)
15+
- [Environment Variables and Modes](#environment-variables-and-modes)
16+
- [Development](#development)
217

318
## Introduction
419

5-
## The CLI
20+
Vue CLI is a full system for rapid Vue.js development, providing:
21+
22+
- Interactive project scaffolding via `@vue/cli`.
23+
- Zero config rapid prototyping via `@vue/cli` + `@vue/cli-service-global`.
24+
- A runtime dependency (`@vue/cli-service`) that is:
25+
- Upgradeable;
26+
- Built on top of webpack, with sensible defaults;
27+
- Configurable via in-project config file;
28+
- Extensible via plugins
29+
- A rich collection of official plugins integrating the best tools in the frontend ecosystem.
30+
31+
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.
32+
33+
## CLI
34+
35+
The CLI is installed globally and provides the `vue` command in your terminal:
36+
37+
``` sh
38+
npm install -g @vue/cli
39+
vue create my-project
40+
```
41+
42+
For full details on what the `vue` command can do, see the [full CLI docs](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli/README.md).
43+
44+
## CLI Service
45+
46+
`@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. The binary exposes commands such as ` A3E2 vue-cli-service serve`, which can be used in npm scripts. 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.
647

748
## Configuration
849

9-
### Vue CLI options
50+
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.
51+
52+
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.
53+
54+
### vue.config.js
55+
56+
Many aspects of a Vue CLI project can be configured by placing a `vue.config.js` file at the root of your project. The file may already exist depending on the features you selected when creating the project.
57+
58+
`vue.config.js` should export an object, for example:
59+
60+
``` js
61+
// vue.config.js
62+
module.exports = {
63+
lintOnSave: true
64+
}
65+
```
66+
67+
Check [here](./config.md) for full list of possible options.
68+
69+
### webpack
1070

11-
### Modes and Environment Variables
71+
Probably the most common configuration need is tweaking the internal webpack config. Vue CLI provides flexible ways to achieve that without ejecting.
1272

13-
### Webpack
73+
See [here](./webpack.md) for full details.
1474

15-
- #### Basic Configuration
75+
### browserlist
1676

17-
- #### Chaining
77+
You will notice a `browserlist` 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.
1878

19-
- #### Using Resolved Config as a File
79+
See [here](https://github.com/ai/browserslist) for how to specify browser ranges.
2080

2181
### Babel
2282

23-
- link to: babel preset
24-
- link to: babel plugin
83+
Babel can be configured via `.babelrc` or the `babel` field in `package.json`.
2584

26-
### CSS
85+
All Vue CLI apps use `@vue/babel-preset-app` by default, which includes:
86+
87+
- [babel-preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env)
88+
- [dynamic import syntax](https://github.com/tc39/proposal-dynamic-import)
89+
- [Object rest spread](https://github.com/tc39/proposal-object-rest-spread)
90+
- [babel-preset-stage-2](https://github.com/babel/babel/tree/master/packages/babel-preset-stage-2)
91+
- Vue JSX support
2792

28-
- #### PostCSS
93+
See [@vue/babel-preset-app](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/babel-preset-app) for preset options.
94+
95+
### CSS
2996

30-
- #### CSS Modules
97+
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/).
3198

32-
- #### Other Pre-Processors
99+
See [here](./css.md) for more details on CSS related configurations.
33100

34101
### ESLint
35102

36-
- link to: eslint plugin
103+
ESLint can be configured via `.eslintrc` or `eslintConfig` field in `package.json`.
104+
105+
See [@vue/cli-plugin-eslint](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-eslint) for more details.
37106

38107
### TypeScript
39108

40-
- link to: typescript plugin
109+
TypeScript can be configured via `tsconfig.json`.
110+
111+
See [@vue/cli-plugin-typescript](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-typescript) for more details.
41112

42113
### Unit Testing
43114

44115
- #### Jest
45116

117+
See [@vue/cli-plugin-unit-jest](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest) for more details.
118+
46119
- #### Mocha (via `mocha-webpack`)
47120

121+
See [@vue/cli-plugin-unit-mocha](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha) for more details.
122+
48123
### E2E Testing
49124

50125
- #### Cypress
51126

127+
See [@vue/cli-plugin-e2e-cypress](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-cypress) for more details.
128+
52129
- #### Nightwatch
130+
131+
See [@vue/cli-plugin-e2e-nightwatch](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-e2e-nightwatch) for more details.
132+
133+
## Environment Variables and Modes
134+
135+
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.
136+
137+
Vue CLI has comprehensive support for specifying different environment variables - see the [dedicated section](./env.md) for more details.
138+
139+
## Development
140+
141+
- [Contributing Guide](https://github.com/vuejs/vue-cli/blob/dev/.github/CONTRIBUTING.md)
142+
- [Plugin Development Guide](https://github.com/vuejs/vue-cli/blob/dev/docs/plugin.md).

‎docs/config.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
## `vue.config.js`
2+
3+
Here are all the available options with default values (all optional):
4+
5+
``` js
6+
module.exports = {
7+
// Project deployment base
8+
// By default we assume your app will be deployed at the root of a domain,
9+
// e.g. https://www.my-app.com/
10+
// If your app is deployed at a sub-path, you will need to specify that
11+
// sub-path here. For example, if your app is deployed at
12+
// https://www.foobar.com/my-app/
13+
// then change this to '/my-app/'
14+
baseUrl: '/',
15+
16+
// where to output built files
17+
outputDir: 'dist',
18+
19+
// whether to use eslint-loader for lint on save.
20+
lintOnSave: false,
21+
22+
// use the full build with in-browser compiler?
23+
// https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only
24+
compiler: false,
25+
26+
// tweak internal webpack configuration.
27+
// see https://github.com/vuejs/vue-cli/blob/dev/docs/webpack.md
28+
chainWebpack: () => {},
29+
configureWebpack: () => {},
30+
31+
// vue-loader options
32+
// https://vue-loader.vuejs.org/en/options.html
33+
vueLoader: {},
34+
35+
// generate sourceMap for production build?
36+
productionSourceMap: true,
37+
38+
// CSS related options
39+
css: {
40+
// extract CSS in components into a single CSS file (only in production)
41+
extract: true,
42+
43+
// enable CSS source maps?
44+
sourceMap: false,
45+
46+
// pass custom options to pre-processor loaders. e.g. to pass options to
47+
// sass-loader, use { sass: { ... } }
48+
loaderOptions: {},
49+
50+
// Enable CSS modules for all css / pre-processor files.
51+
// This option does not affect *.vue files.
52+
modules: false
53+
},
54+
55+
// use thread-loader for babel & TS in production build
56+
// enabled by default if the machine has more than 1 cores
57+
parallel: require('os').cpus().length > 1,
58+
59+
// split vendors using autoDLLPlugin?
60+
// can also be an explicit Array of dependencies to include in the DLL chunk.
61+
dll: false,
62+
63+
// options for the PWA plugin.
64+
// see https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa
65+
pwa: {},
66+
67+
// configure webpack-dev-server behavior
68+
devServer: {
69+
open: process.platform === 'darwin',
70+
host: '0.0.0.0',
71+
port: 8080,
72+
https: false,
73+
hotOnly: false,
74+
proxy: null, // string | Object
75+
before: app => {}
76+
},
77+
78+
// options for 3rd party plugins
79+
pluginOptions: {
80+
// ...
81+
}
82+
}
83+
```

‎docs/css.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
## CSS
2+
3+
### < 10000 span class="pl-en">PostCSS
4+
5+
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).
6+
7+
### CSS Modules
8+
9+
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>`.
10+
11+
As for standalone style files, any files ending with `.module.(css|sass|scss|less|styl|stylus)` will be processed as CSS modules.
12+
13+
If you wish to be able to use CSS modules without the `.module` postfix, you can set `css: { modules: true }` in `vue.config.js`. This option does not affect `*.vue` files.
14+
15+
### Pre-Processors
16+
17+
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:
18+
19+
``` sh
20+
npm install -D sass-loader node-sass
21+
```
22+
23+
Then you can import `.scss` files, or use it in `*.vue` files with:
24+
25+
``` vue
26+
<style lang="scss">
27+
$color = red;
28+
</style>
29+
```
30+
31+
### Passing Options to Pre-Processor Loaders
32+
33+
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:
34+
35+
``` js
36+
// vue.config.js
37+
const fs = require('fs')
38+
39+
module.exports = {
40+
css: {
41+
loaderOptions: {
42+
sass: {
43+
data: fs.readFileSync('src/variables.scss', 'utf-8')
44+
}
45+
}
46+
}
47+
}
48+
```

‎docs/env.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
## Environment Variables and Modes
2+
3+
You can specify env variables by placing the following files in your project root:
4+
5+
``` sh
6+
.env # loaded in all cases
7+
.env.local # loaded in all cases, ignored by git
8+
.env.[mode] # only loaded in specified mode
9+
.env.[mode].local # only loaded in specified mode, ignored by git
10+
```
11+
12+
An env file simply contains key=value pairs of environment variables:
13+
14+
```
15+
FOO=bar
16+
VUE_APP_SECRET=secret
17+
```
18+
19+
Loaded variables will become available to all `vue-cli-service` commands, plugins and dependencies.
20+
21+
### Modes
22+
23+
**Mode** is an important concept in Vue CLI projects. By default, there are three modes in a Vue CLI project:
24+
25+
- `development` is used by `vue-cli-service serve`
26+
- `production` is used by `vue-cli-service build`
27+
- `test` is used by `vue-cli-service test`
28+
29+
Note that a mode is different from `NODE_ENV`, as a mode can contain multiple environment variables. That said, each mode does set `NODE_ENV` to the same value by default - for example, `NODE_ENV` will be set to `"development"` in development mode.
30+
31+
You can set environment variables only available to a certain mode by postfixing the `.env` file. For example, if you create a file named `.env.development` in your project root, then the variables declared in that file will only be loaded in development mode.
32+
33+
### Using Env Variables in Client-side Code
34+
35+
Only variables that start with `VUE_APP_` will be statically embedded into the client bundle with `webpack.DefinePlugin`. You can access them in your application code:
36+
37+
``` js
38+
console.log(process.env.VUE_APP_SECRET)
39+
```
40+
41+
During build, `process.env.VUE_APP_SECRET` will be replaced by the corresponding value. In the case of `VUE_APP_SECRET=secret`, it will be replaced by `"secret"`.
42+
43+
In addition to `VUE_APP_*` variables, there are also two special variables that will always be available in your app code:
44+
45+
- `NODE_ENV` - this will be one of `"development"`, `"production"` or `"test"` depending on the [mode](#modes) the app is running in.
46+
- `BASE_URL` - this corresponds to the `baseUrl` option in `vue.config.js` and is the base path your app is deployed at.
47+
48+
### Local Variables
49+
50+
Sometimes you might have env variables that should not be committed into the codebase, especially if your project is hosted in a public repository. In that case you should use an `.env.local` file instead. Local env files are ignored in `.gitignore` by default.
51+
52+
`.local` can also be appended to mode-specific env files, for example `.env.development.local` will be loaded during development, and is ignored by git.

‎docs/webpack.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# WIP
2+
3+
### Basic Configuration
4+
5+
### Chaining
6+
7+
### Using Resolved Config as a File

‎packages/@vue/cli/README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# @vue/cli
22

3-
## Usage
4-
53
``` sh
64
npm install -g @vue/cli
7-
vue create my-app
5+
vue create my-project
86
```
7+
8+
[Full Docs](https://github.com/vuejs/vue-cli/tree/dev/docs)

0 commit comments

Comments
 (0)
0