You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-1Lines changed: 3 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,9 @@
2
2
3
3
> This is the branch for `@vue/cli` 3.0.
4
4
5
-
**Status: alpha**
5
+
## Status: alpha
6
+
7
+
Certain combinations of plugins may not work properly, and things may break until we reach beta phase. Do not use in production yet unless you are adventurous.
A plugin with a generator that injects additional dependencies other than packages in this repo (e.g. `chai` is injected by `@vue/cli-plugin-unit-mocha/generator/index.js`) should have those dependencies listed in its own `devDependencies` field. This ensures that:
6
-
7
-
1. the package always exist in this repo's root `node_modules` so that we don't have to reinstall them on every test.
8
-
9
-
2.`yarn.lock` stays consistent so that CI can better use it for inferring caching behavior.
10
-
11
3
## Core Concepts
12
4
5
+
-[Creator](#creator)
6
+
-[Service](#service)
7
+
-[CLI Plugin](#cli-plugin)
8
+
-[Service Plugin](#service-plugin)
9
+
-[Generator](#generator)
10
+
-[Prompts](#prompts)
11
+
13
12
There are two major parts of the system:
14
13
15
14
-`@vue/cli`: globally installed, exposes the `vue create <app>` command;
@@ -25,17 +24,36 @@ Both utilize a plugin-based architecture.
25
24
26
25
[Service][service-class] is the class created when invoking `vue-cli-service <command> [...args]`. Responsible for managing the internal webpack configuration, and exposes commands for serving and building the project.
27
26
28
-
### Plugin
27
+
### CLI Plugin
28
+
29
+
A CLI plugin is an npm package that can add additional features to a `@vue/cli` project. It should always contain a [Service Plugin](#service-plugin) as its main export, and can optionally contain a [Generator](#generator) and a [Prompt File](#prompts-for-3rd-party-plugins).
30
+
31
+
A typical CLI plugin's folder structure looks like the following:
32
+
33
+
```
34
+
.
35
+
├── README.md
36
+
├── generator.js # generator (optional)
37
+
├── prompts.js # prompts file (optional)
38
+
├── index.js # service plugin
39
+
└── package.json
40
+
```
41
+
42
+
### Service Plugin
43
+
44
+
Service plugins are loaded automatically when a Service instance is created - i.e. every time the `vue-cli-service` command is invoked inside a project.
29
45
30
-
Plugins are locally installed into the project as dependencies. `@vue/cli-service`'s [built-in commands][commands] and [config modules][config] are also all implemented as plugins. This repo also contains a number of plugins that are published as individual packages.
46
+
Note the concept of a "service plugin" we are discussing here is narrower than that of a "CLI plugin", which is published as an npm package. The former only refers to a module that will be loaded by `@vue/cli-service` when it's initialized, and is usually a part of the latter.
31
47
32
-
A plugin should export a function which receives two arguments:
48
+
In addition, `@vue/cli-service`'s [built-in commands][commands] and [config modules][config] are also all implemented as service plugins.
49
+
50
+
A service plugin should export a function which receives two arguments:
33
51
34
52
- A [PluginAPI][plugin-api] instance
35
53
36
-
-Project local options specified in `vue.config.js`, or in the `"vue-cli"` field in `package.json`.
54
+
-An object containing project local options specified in `vue.config.js`, or in the `"vue-cli"` field in `package.json`.
37
55
38
-
The API allows plugins to extend/modify the internal webpack config for different environments and inject additional commands to `vue-cli-service`. Example:
56
+
The API allows service plugins to extend/modify the internal webpack config for different environments and inject additional commands to `vue-cli-service`. Example:
An important thing to note about env variables is knowing when they are resolved. Typically, a command like `vue-cli-service serve` or `vue-cli-service build` will always call `api.setMode()` as the first thing it does. However, this also means those env variables may not yet be available when a service plugin is invoked:
78
+
79
+
```js
80
+
module.exports=api=> {
81
+
process.env.NODE_ENV// may not be resolved yet
82
+
83
+
api.regsiterCommand('build', () => {
84
+
api.setMode('production')
85
+
})
86
+
}
87
+
```
88
+
89
+
Instead, it's safer to rely on env variables in `configureWebpack` or `chainWebpack` functions, which are called lazily only when `api.resolveWebpackConfig()` is finally called:
90
+
91
+
```js
92
+
module.exports=api=> {
93
+
api.configureWebpack(config=> {
94
+
if (process.env.NODE_ENV==='production') {
95
+
// ...
96
+
}
97
+
})
98
+
}
99
+
```
100
+
101
+
#### Custom Options for 3rd Party Plugins
102
+
103
+
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`:
104
+
105
+
```js
106
+
module.exports= {
107
+
pluginOptions: {
108
+
foo: { /* ... */ }
109
+
}
110
+
}
111
+
```
112
+
113
+
The 3rd party plugin can read `projectOptions.pluginOptions.foo` to determine conditional configurations.
114
+
57
115
### Generator
58
116
59
-
A plugin published as a package can also contain a `generator.js` or `generator/index.js` file. The generator inside a plugin will be invoked after the plugin is installed.
117
+
A CLI plugin published as a package can contain a `generator.js` or `generator/index.js` file. The generator inside a plugin will be invoked in two possible scenarios:
118
+
119
+
- During a project's initial creation, if the CLI plugin is installed as part of the project creation preset.
120
+
121
+
- When the plugin is installed after project's creation and invoked individually via `vue invoke`.
60
122
61
123
The [GeneratorAPI][generator-api] allows a generator to inject additional dependencies or fields into `package.json` and add files to the project.
62
124
63
125
A generator should export a function which receives three arguments:
64
126
65
127
1. A `GeneratorAPI` instance;
66
128
67
-
2. The generator options for this plugin. These options are resolved during the prompt phase of project creation, or loaded from a saved `~/.vuerc`. For example, if the saved `~/.vuerc` looks like this:
129
+
2. The generator options for this plugin. These options are resolved during the prompt phase of project creation, or loaded from a saved preset in `~/.vuerc`. For example, if the saved `~/.vuerc` looks like this:
68
130
69
131
```json
70
132
{
71
-
"plugins": {
72
-
"@vue/cli-plugin-foo": { "option": "bar" }
133
+
"presets" : {
134
+
"foo": {
135
+
"plugins": {
136
+
"@vue/cli-plugin-foo": { "option": "bar" }
137
+
}
138
+
}
73
139
}
74
140
}
75
141
```
76
142
77
-
Then the plugin `@vue/cli-plugin-foo` will receive `{ option: 'bar' }` as its second argument.
143
+
And if the user creates a project using the `foo` preset, then the generator of `@vue/cli-plugin-foo` will receive `{ option: 'bar' }` as its second argument.
144
+
145
+
For a 3rd party plugin, the options will be resolved from the prompts or command line arguments when the user executes `vue invoke` (see [Prompts for 3rd Party Plugins](#prompts-for-3rd-party-plugins)).
78
146
79
-
3. The entire `.vuerc` object will be passed as the third argument.
147
+
3. The entire preset (`presets.foo`) will be passed as the third argument.
Currently, only built-in plugins have the ability to customize the prompts when creating a new project, and the prompt modules are located [inside the `@vue/cli` package][prompt-modules].
171
+
#### Prompts for Built-in Plugins
172
+
173
+
Only built-in plugins have the ability to customize the initial prompts when creating a new project, and the prompt modules are located [inside the `@vue/cli` package][prompt-modules].
104
174
105
175
A prompt module should export a function that receives a [PromptModuleAPI][prompt-api] instance. The prompts are presented using [inquirer](https://github.com/SBoudrias/Inquirer.js) under the hood:
106
176
@@ -133,6 +203,26 @@ module.exports = api => {
133
203
}
134
204
```
135
205
206
+
#### Prompts for 3rd Party Plugins
207
+
208
+
3rd party plugins are typically installed manually after a project is already created, and the user will initialize the plugin by calling `vue invoke`. If the plugin contains a `prompt.js` in its root directory, it will be used during invocation. The file should export an array of [Questions](https://github.com/SBoudrias/Inquirer.js#question) that will be handled by Inquirer.js. The resolved answers object will be passed to the plugin's generator as options.
209
+
210
+
Alternatively, the user can skip the prompts and directly initialize the plugin by passing options via the command line, e.g.:
211
+
212
+
```sh
213
+
vue invoke my-plugin --mode awesome
214
+
```
215
+
216
+
## Note on Development of Core Plugins
217
+
218
+
> This section only applies if you are working on a built-in plugin inside this very repository.
219
+
220
+
A plugin with a generator that injects additional dependencies other than packages in this repo (e.g. `chai` is injected by `@vue/cli-plugin-unit-mocha/generator/index.js`) should have those dependencies listed in its own `devDependencies` field. This ensures that:
221
+
222
+
1. the package always exist in this repo's root `node_modules` so that we don't have to reinstall them on every test.
223
+
224
+
2.`yarn.lock` stays consistent so that CI can better use it for inferring caching behavior.
0 commit comments