mirror of
https://github.com/vuejs/vue-cli.git
synced 2026-04-23 04:58:56 -05:00
docs: progress
This commit is contained in:
Evan You
@@ -98,6 +98,38 @@ module.exports = api => {
|
||||
}
|
||||
```
|
||||
|
||||
#### Resolving Webpack Config in Plugins
|
||||
|
||||
A plugin can retrieve the resolved webpack config by calling `api.resolveWebpackConfig()`. Every call generates a fresh webpack config which can be further mutated as needed:
|
||||
|
||||
``` js
|
||||
api.regsiterCommand('my-build', args => {
|
||||
// make sure to set mode and load env variables
|
||||
api.setMode('production')
|
||||
|
||||
const configA = api.resolveWebpackConfig()
|
||||
const configB = api.resolveWebpackConfig()
|
||||
|
||||
// mutate configA and configB for different purposes...
|
||||
})
|
||||
```
|
||||
|
||||
Alternatively, a plugin can also obtain a fresh [chainable config](https://github.com/mozilla-neutrino/webpack-chain) by calling `api.resolveChainableWebpackConfig()`:
|
||||
|
||||
``` js
|
||||
api.regsiterCommand('my-build', args => {
|
||||
api.setMode('production')
|
||||
|
||||
const configA = api.resolveChainableWebpackConfig()
|
||||
const configB = api.resolveChainableWebpackConfig()
|
||||
|
||||
// chain-modify configA and configB for different purposes...
|
||||
|
||||
const finalConfigA = configA.toConfig()
|
||||
const finalConfigB = configB.toConfig()
|
||||
})
|
||||
```
|
||||
|
||||
#### Custom Options for 3rd Party Plugins
|
||||
|
||||
The exports from `vue.config.js` will be [validated against a schema](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-service/lib/options.js#L3) to avoid typos and wrong config values. However, a 3rd party plugin can still allow the user to configure its behavior via the `pluginOptions` field. For example, with the following `vue.config.js`:
|
||||
|
||||
+24
-1
@@ -43,7 +43,30 @@ For full details on what the `vue` command can do, see the [full CLI docs](./cli
|
||||
|
||||
## CLI Service
|
||||
|
||||
`@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 `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.
|
||||
`@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.
|
||||
|
||||
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:
|
||||
|
||||
``` json
|
||||
{
|
||||
"scripts": {
|
||||
"serve": "vue-cli-service serve --open",
|
||||
"build": "vue-cli-service build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
``` sh
|
||||
./node_modules/.bin/vue-cli-service help
|
||||
```
|
||||
|
||||
You can also learn about the available options of each command with:
|
||||
|
||||
``` sh
|
||||
./node_modules/.bin/vue-cli-service help [command]
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
+54
-1
@@ -1,4 +1,36 @@
|
||||
## CLI Usage
|
||||
## CLI
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [Creating a New Project](#creating-a-new-project)
|
||||
- [Zero-config Prototyping](#zero-config-prototyping)
|
||||
- [Installing Plugins in an Existing Project](#installing-plugins-in-an-existing-project)
|
||||
- [Inspecting the webpack Config](#inspecting-the-projects-webpack-config)
|
||||
- [Pulling 2.x Templates](#pulling-vue-cli2x-templates-legacy)
|
||||
|
||||
### Installation
|
||||
|
||||
``` sh
|
||||
npm install -g @vue/cli
|
||||
vue create my-project
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
Usage: vue <command> [options]
|
||||
|
||||
Commands:
|
||||
|
||||
create [options] <app-name> create a new project powered by vue-cli-service
|
||||
invoke <plugin> [pluginOptions] invoke the generator of a plugin in an already created project
|
||||
inspect [options] [paths...] inspect the webpack config in a project with vue-cli-service
|
||||
serve [options] [entry] serve a .js or .vue file in development mode with zero config
|
||||
build [options] [entry] build a .js or .vue file in production mode with zero config
|
||||
init <template> <app-name> generate a project from a remote template (legacy API, requires @vue/cli-init)
|
||||
```
|
||||
|
||||
For each command, you can also use `vue <command> --help` to see more detailed usage.
|
||||
|
||||
### Creating a New Project
|
||||
|
||||
@@ -47,6 +79,27 @@ vue invoke eslint --config airbnb --lintOn save
|
||||
|
||||
It is recommended to commit your project's current state before running `vue invoke`, so that after file generation you can review the changes and revert if needed.
|
||||
|
||||
### Inspecting the Project's Webpack Config
|
||||
|
||||
Since `@vue/cli-service` abstracts away the webpack config, it may be more difficult to understand what is included in the config, especially when you are trying to make tweaks yourself.
|
||||
|
||||
`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:
|
||||
|
||||
``` sh
|
||||
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:
|
||||
|
||||
``` sh
|
||||
# only inspect the first rule
|
||||
vue inspect module.rules.0
|
||||
```
|
||||
|
||||
### Pulling `vue-cli@2.x` Templates (Legacy)
|
||||
|
||||
`@vue/cli` uses the same `vue` binary, so it overwrites `vue-cli@2.x`. If you still need the legacy `vue init` functionality, you can install a global bridge:
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
## CSS
|
||||
|
||||
- [PostCSS](#postcss)
|
||||
- [CSS Modules](#css-modules)
|
||||
- [Pre-Processors](#pre-processors)
|
||||
- [Passing Options to Pre-Processor Loaders](#passing-options-to-pre-processor-loaders)
|
||||
|
||||
### 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).
|
||||
|
||||
+8
-1
@@ -1,5 +1,12 @@
|
||||
## Environment Variables and Modes
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Modes](#modes)
|
||||
- [Using Env Variables in Client-side Code](#using-env-variables-in-client-side-code)
|
||||
- [Local Only Variables](#local-only-variables)
|
||||
|
||||
### Overview
|
||||
|
||||
You can specify env variables by placing the following files in your project root:
|
||||
|
||||
``` sh
|
||||
@@ -45,7 +52,7 @@ In addition to `VUE_APP_*` variables, there are also two special variables that
|
||||
- `NODE_ENV` - this will be one of `"development"`, `"production"` or `"test"` depending on the [mode](#modes) the app is running in.
|
||||
- `BASE_URL` - this corresponds to the `baseUrl` option in `vue.config.js` and is the base path your app is deployed at.
|
||||
|
||||
### Local Variables
|
||||
### Local Only Variables
|
||||
|
||||
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.
|
||||
|
||||
|
||||
+103
-2
@@ -1,7 +1,108 @@
|
||||
# WIP
|
||||
## Configuring webpack
|
||||
|
||||
- [Basic Configuration](#basic-configuration)
|
||||
- [Chaining](#chaining-advanced)
|
||||
- [Inspecting the Config](#inspecting-the-projects-webpack-config)
|
||||
- [Using Resolved Config as a File](#using-resolved-config-as-a-file)
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
### Chaining
|
||||
The easiest way to tweak the webpack config is provide an object to the `configureWebpack` option in `vue.config.js`:
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: {
|
||||
plugins: [
|
||||
new MyAwesomeWebpackPlugin()
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The object will be merged into the final webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
|
||||
|
||||
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
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
configureWebpack: config => {
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
// mutate config for production...
|
||||
} else {
|
||||
// mutate for development...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Chaining (Advanced)
|
||||
|
||||
The internal webpack config is maintained using [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). The library provides an abstraction over the raw webpack config, with the ability to define named loader rules and named plugins, and later "tap" into those rules and modify their options.
|
||||
|
||||
This allows us finer-grained control over the internal config. Here are some examples:
|
||||
|
||||
#### Transpiling a Dependency Module
|
||||
|
||||
By default the Babel configuration skips
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.rule('js')
|
||||
.include
|
||||
.add(/some-module-to-transpile/)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Modifying Plugin Options
|
||||
|
||||
``` js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
chainWebpack: config => {
|
||||
config
|
||||
.plugin('html')
|
||||
.tap(args => {
|
||||
return [/* new args to pass to html-webpack-plugin's constructor */]
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You will need to familiarize yourself with [webpack-chain's API](https://github.com/mozilla-neutrino/webpack-chain#getting-started) and [read some source code](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-service/lib/config) in order to understand how to leverage the full power of this option, but it gives you a more expressive and safer way to modify the webpack config than directly mutation values.
|
||||
|
||||
### Inspecting the Project's Webpack Config
|
||||
|
||||
Since `@vue/cli-service` abstracts away the webpack config, it may be more difficult to understand what is included in the config, especially when you are trying to make tweaks yourself.
|
||||
|
||||
`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:
|
||||
|
||||
``` sh
|
||||
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:
|
||||
|
||||
``` sh
|
||||
# only inspect the first rule
|
||||
vue inspect module.rules.0
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
<projectRoot>/node_modules/@vue/cli-service/webpack.config.js
|
||||
```
|
||||
|
||||
This file dynamically resolves and exports the exact same webpack config used in `vue-cli-service` commands, including those from plugins and even your custom configurations.
|
||||
|
||||
Reference in New Issue
Block a user