Skip to content

Commit 4b2a11e

Browse files
NataliaTepluhinaAkryum
NataliaTepluhina
authored and
Akryum
committed
docs: Plugin development guide (#2973)
* feat(docs): add Heroku deployment section * fix: rename remote repository section title * fix(docs): add a middleware for handling vue-router in deployed app * fix(docs): fixed formatting * feat: Create structure for Plugin and Generator API; create Getting started and Modifying webpack config chapters * feat: started registerCommand description * feat: Add a description for adding new vue-cli-service command * fix: Change the part about modifying existing vue-cli-service commands * feat: Add local installation steps for cli-plugin with/without Vue UI * feat: Add generator extending package and changing main file chapters * feat: Create structure for Plugin and Generator API; create Getting started and Modifying webpack config chapters * feat: started registerCommand description * feat: Add a description for adding new vue-cli-service command * fix: Change the part about modifying existing vue-cli-service commands * feat: Add local installation steps for cli-plugin with/without Vue UI * feat: Add generator extending package and changing main file chapters * feat: Add templating part to vue-cli-plugin Generator docs * feat: described prompts * fix: fixed condition on template rendering in generator * fix: changed Getting Started part * fix: Added links to Generator and Prompts chapters; fixed a description for testing a plugin locally * fix: reverted changed to Heroku deployment * fix: restored Surge chapter * fix: deleted unused image * fix: changed an order of chapters; added description for Generator part * Update docs/dev-guide/plugin-dev.md Co-Authored-By: NataliaTepluhina <[email protected]> * fix: rewrote the Generator part * feat: add description for extending a package with new command * fix: fixed service plugin description and links * fix: fixed links and typos, added prompt API * feat: UI description and augmenting task in the UI * feat: added a description for configuration screen in UI * feat: add configuration files description * feat: add save config description * feat: add prompts-in-UI description * feat: added logo and discoverability sections * feat: add publish plugin to npm section * feat: stated plugin API reference * fix: fixed typo in quote * feat: Plugin API reference ready * fix: removed examples * feat: add Generator API reference * fix: fixed typo in prompt Co-Authored-By: NataliaTepluhina <[email protected]> * fix: remove underscore in `_path` parameter * Update docs/dev-guide/plugin-dev.md Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add export to the templating example * fix: change preposition Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add missing `{` * Update docs/dev-guide/plugin-dev.md Co-Authored-By: NataliaTepluhina <[email protected]> * fix: specified that package.json should be user's one Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add dot Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add dot Co-Authored-By: NataliaTepluhina <[email protected]> * fix: missing bracket Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add dot Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add dot Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add dot Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add colon Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add semicolon Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add semicolon Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add semicolon Co-Authored-By: NataliaTepluhina <[email protected]> * fix: typo in `it's` vs `its` Co-Authored-By: NataliaTepluhina <[email protected]> * feat: add more places for logo to display Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add vue add option to invocation Co-Authored-By: NataliaTepluhina <[email protected]> * fix: add fe missed brackets and moved filename section * fix: fix indentations and remove OPTIONS constant * fix: fix indentation and wrap built-in plugin description with a tip * fix: add link to Public static files * fix: change the description for UI prompts properties * fix: add `@scope/vue-cli-plugin-<name>` option * fix: code style fixes * fix: change config id to follow reverse domain name notation * fix: style fixes * feat: add more comments with file names * docs: fixes * docs: removed built-it plugins prompts part
1 parent 702a2c9 commit 4b2a11e

15 files changed

+935
-195
lines changed

‎docs/.vuepress/config.js

+8
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,14 @@ module.exports = {
109109
],
110110
'/dev-guide/': [
111111
'/dev-guide/plugin-dev.md',
112+
{
113+
title: 'API reference',
114+
collapsable: false,
115+
children: [
116+
'/dev-guide/plugin-api.md',
117+
'/dev-guide/generator-api.md',
118+
]
119+
},
112120
{
113121
title: 'UI Development',
114122
collapsable: false,

‎docs/.vuepress/public/generator-template.png

50.7 KB
Loading

‎docs/.vuepress/public/prompts-example.png

62.3 KB
Loading

‎docs/.vuepress/public/ui-browse-local-plugin.png

309 KB
Loading

‎docs/.vuepress/public/ui-config-start.png

143 KB
Loading

‎docs/.vuepress/public/ui-configuration-default.png

331 KB
Loading

‎docs/.vuepress/public/ui-configuration.png

287 KB
Loading

‎docs/.vuepress/public/ui-greet-task.png

179 KB
Loading

‎docs/.vuepress/public/ui-plugin-refresh.png

248 KB
Loading

‎docs/.vuepress/public/ui-project-manager.png

309 KB
Loading

‎docs/.vuepress/public/ui-prompts.png

152 KB
Loading

‎docs/.vuepress/public/ui-select-plugin.png

247 KB
Loading

‎docs/dev-guide/generator-api.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Generator API
2+
3+
## resolve
4+
5+
- **Arguments**
6+
- `{string} _path` - relative path from project root
7+
8+
- **Returns**
9+
- `{string}`- the resolved absolute path
10+
11+
- **Usage**:
12+
Resolve a path for the current project
13+
14+
## hasPlugin
15+
16+
- **Arguments**
17+
- `{string} id` - plugin id, can omit the (@vue/|vue-|@scope/vue)-cli-plugin- prefix
18+
19+
- **Returns**
20+
- `{boolean}`
21+
22+
- **Usage**:
23+
Check if the project has a plugin with given id
24+
25+
## addConfigTransform
26+
27+
- **Arguments**
28+
- `{string} key` - config key in package.json
29+
- `{object} options` - options
30+
- `{object} options.file` - file descriptor. Used to search for existing file. Each key is a file type (possible values: ['js', 'json', 'yaml', 'lines']). The value is a list of filenames.
31+
Example:
32+
```js
33+
{
34+
js: ['.eslintrc.js'],
35+
json: ['.eslintrc.json', '.eslintrc']
36+
}
37+
```
38+
By default, the first filename will be used to create the config file.
39+
40+
- **Returns**
41+
- `{boolean}`
42+
43+
- **Usage**:
44+
Configure how config files are extracted.
45+
46+
## extendPackage
47+
48+
- **Arguments**
49+
- `{object | () => object} fields` - fields to merge
50+
51+
- **Usage**:
52+
Extend the `package.json` of the project. Nested fields are deep-merged unless `{ merge: false }` is passed. Also resolves dependency conflicts between plugins. Tool configuration fields may be extracted into standalone files before files are written to disk.
53+
54+
## render
55+
56+
- **Arguments**
57+
- `{string | object | FileMiddleware} source` - can be one of
58+
- relative path to a directory;
59+
- object hash of `{ sourceTemplate: targetFile }` mappings;
60+
- a custom file middleware function
61+
- `{object} [additionalData]` - additional data available to templates
62+
- `{object} [ejsOptions]` - options for ejs
63+
64+
- **Usage**:
65+
Render template files into the virtual files tree object.
66+
67+
## postProcessFiles
68+
69+
- **Arguments**
70+
- `{FileMiddleware} cb` - file middleware
71+
72+
- **Usage**:
73+
Push a file middleware that will be applied after all normal file middlewares have been applied.
74+
75+
## onCreateComplete
76+
77+
- **Arguments**
78+
- `{function} cb`
79+
80+
- **Usage**:
81+
Push a callback to be called when the files have been written to disk.
82+
83+
## exitLog
84+
85+
- **Arguments**
86+
- `{} msg` - string or value to print after the generation is completed;
87+
- `{('log'|'info'|'done'|'warn'|'error')} [type='log']` - type of the message.
88+
89+
- **Usage**:
90+
Add a message to be printed when the generator exits (after any other standard messages).
91+
92+
## genJSConfig
93+
94+
- **Arguments**
95+
- `{any} value`
96+
97+
- **Usage**:
98+
Convenience method for generating a JS config file from JSON
99+
100+
## injectImports
101+
102+
- **Arguments**
103+
- `{string} file` - target file to add imports
104+
- `{string | [string]} imports` - imports string/array
105+
106+
- **Usage**:
107+
Add import statements to a file.
108+
109+
## injectRootOptions
110+
111+
- **Arguments**
112+
- `{string} file` - target file to add options
113+
- `{string | [string]} options` - options string/array
114+
115+
- **Usage**:
116+
Add options to the root Vue instance (detected by `new Vue`).
117+
118+
## entryFile
119+
120+
- **Returns**
121+
- `{('src/main.ts'|'src/main.js')}`
122+
123+
- **Usage**:
124+
Get the entry file taking into account typescript.
125+
126+
## invoking
127+
128+
- **Returns**
129+
- `{boolean}`
130+
131+
- **Usage**:
132+
Checks if the plugin is being invoked.
133+

‎docs/dev-guide/plugin-api.md

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Plugin API
2+
3+
## getCwd
4+
5+
- **Usage**:
6+
Returns a current working directory
7+
8+
## resolve
9+
10+
- **Arguments**
11+
- `{string} path` - relative path from project root
12+
13+
- **Returns**
14+
- `{string}`- the resolved absolute path
15+
16+
- **Usage**:
17+
Resolve a path for the current project
18+
19+
## hasPlugin
20+
21+
- **Arguments**
22+
- `{string} id` - plugin id, can omit the (@vue/|vue-|@scope/vue)-cli-plugin- prefix
23+
24+
- **Returns**
25+
- `{boolean}`
26+
27+
- **Usage**:
28+
Check if the project has a plugin with given id
29+
30+
## registerCommand
31+
32+
- **Arguments**
33+
- `{string} name`
34+
- `{object} [opts]`
35+
```js
36+
{
37+
description: string,
38+
usage: string,
39+
options: { [string]: string }
40+
}
41+
```
42+
- `{function} fn`
43+
```js
44+
(args: { [string]: string }, rawArgs: string[]) => ?Promise
45+
```
46+
47+
- **Usage**:
48+
Register a command that will become available as `vue-cli-service [name]`.
49+
50+
## chainWebpack
51+
52+
- **Arguments**
53+
- `{function} fn`
54+
55+
- **Usage**:
56+
Register a function that will receive a chainable webpack config. This function is lazy and won't be called until `resolveWebpackConfig` is called.
57+
58+
59+
## configureWebpack
60+
61+
- **Arguments**
62+
- `{object | function} fn`
63+
64+
- **Usage**:
65+
Register a webpack configuration object that will be merged into the config **OR** a function that will receive the raw webpack config. The function can either mutate the config directly or return an object
66+
that will be merged into the webpack config.
67+
68+
## configureDevServer
69+
70+
- **Arguments**
71+
- `{object | function} fn`
72+
73+
- **Usage**:
74+
Register a dev serve config function. It will receive the express `app` instance of the dev server.
75+
76+
## resolveWebpackConfig
77+
78+
- **Arguments**
79+
- `{ChainableWebpackConfig} [chainableConfig]`
80+
- **Returns**
81+
- `{object}` - raw webpack config
82+
83+
- **Usage**:
84+
Resolve the final raw webpack config, that will be passed to webpack.
85+
86+
## resolveChainableWebpackConfig
87+
88+
- **Returns**
89+
- `{ChainableWebpackConfig}`
90+
91+
- **Usage**:
92+
Resolve an intermediate chainable webpack config instance, which can be further tweaked before generating the final raw webpack config. You can call this multiple times to generate different branches of the base webpack config.
93+
94+
See [https://github.com/mozilla-neutrino/webpack-chain](https://github.com/mozilla-neutrino/webpack-chain)
95+
96+
## genCacheConfig
97+
98+
- **Arguments**
99+
- `id`
100+
- `partialIdentifier`
101+
- `configFiles`
102+
- **Returns**
103+
- `{object}`
104+
```js
105+
{
106+
cacheDirectory: string,
107+
cacheIdentifier: string }
108+
```
109+
110+
- **Usage**:
111+
Generate a cache identifier from a number of variables.
112+

0 commit comments

Comments
 (0)