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 <NataliaTepluhina@users.noreply.github.com> * 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 <NataliaTepluhina@users.noreply.github.com> * fix: remove underscore in `_path` parameter * Update docs/dev-guide/plugin-dev.md Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add export to the templating example * fix: change preposition Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add missing `{` * Update docs/dev-guide/plugin-dev.md Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: specified that package.json should be user's one Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add dot Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add dot Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: missing bracket Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add dot Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add dot Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add dot Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add colon Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add semicolon Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add semicolon Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add semicolon Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: typo in `it's` vs `its` Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * feat: add more places for logo to display Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * fix: add vue add option to invocation Co-Authored-By: NataliaTepluhina <NataliaTepluhina@users.noreply.github.com> * 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
vuejs · Jan 25, 2019 · 4b2a11e · 4b2a11e
1 parent 702a2c9
commit 4b2a11e
Show file tree

Hide file tree

Showing 15 changed files with 935 additions and 195 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -109,6 +109,14 @@ module.exports = {
           ],
           '/dev-guide/': [
             '/dev-guide/plugin-dev.md',
+            {
+              title: 'API reference',
+              collapsable: false,
+              children: [
+                '/dev-guide/plugin-api.md',
+                '/dev-guide/generator-api.md',
+              ]
+            },
             {
               title: 'UI Development',
               collapsable: false,

diff --git a/docs/.vuepress/public/generator-template.png b/docs/.vuepress/public/generator-template.png
diff --git a/docs/.vuepress/public/prompts-example.png b/docs/.vuepress/public/prompts-example.png
diff --git a/docs/.vuepress/public/ui-browse-local-plugin.png b/docs/.vuepress/public/ui-browse-local-plugin.png
diff --git a/docs/.vuepress/public/ui-config-start.png b/docs/.vuepress/public/ui-config-start.png
diff --git a/docs/.vuepress/public/ui-configuration-default.png b/docs/.vuepress/public/ui-configuration-default.png
diff --git a/docs/.vuepress/public/ui-configuration.png b/docs/.vuepress/public/ui-configuration.png
diff --git a/docs/.vuepress/public/ui-greet-task.png b/docs/.vuepress/public/ui-greet-task.png
diff --git a/docs/.vuepress/public/ui-plugin-refresh.png b/docs/.vuepress/public/ui-plugin-refresh.png
diff --git a/docs/.vuepress/public/ui-project-manager.png b/docs/.vuepress/public/ui-project-manager.png
diff --git a/docs/.vuepress/public/ui-prompts.png b/docs/.vuepress/public/ui-prompts.png
diff --git a/docs/.vuepress/public/ui-select-plugin.png b/docs/.vuepress/public/ui-select-plugin.png
diff --git a/docs/dev-guide/generator-api.md b/docs/dev-guide/generator-api.md
@@ -0,0 +1,133 @@
+# Generator API
+
+## resolve
+
+- **Arguments**
+  - `{string} _path` - relative path from project root
+
+- **Returns**
+  - `{string}`- the resolved absolute path
+
+- **Usage**:
+Resolve a path for the current project
+
+## hasPlugin
+
+- **Arguments**
+  - `{string} id` - plugin id, can omit the (@vue/|vue-|@scope/vue)-cli-plugin- prefix
+
+- **Returns**
+  - `{boolean}`
+
+- **Usage**:
+Check if the project has a plugin with given id
+
+## addConfigTransform
+
+- **Arguments**
+  - `{string} key` - config key in package.json
+  - `{object} options` - options
+  - `{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.
+  Example:
+  ```js
+  {
+    js: ['.eslintrc.js'],
+    json: ['.eslintrc.json', '.eslintrc']
+  }
+  ```
+  By default, the first filename will be used to create the config file.
+
+- **Returns**
+  - `{boolean}`
+
+- **Usage**:
+Configure how config files are extracted.
+
+## extendPackage
+
+- **Arguments**
+  - `{object | () => object} fields` - fields to merge
+
+- **Usage**:
+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.
+
+## render
+
+- **Arguments**
+  - `{string | object | FileMiddleware} source` - can be one of
+    - relative path to a directory;
+    - object hash of `{ sourceTemplate: targetFile }` mappings;
+    - a custom file middleware function
+  - `{object} [additionalData]` - additional data available to templates
+  - `{object} [ejsOptions]` - options for ejs
+
+- **Usage**:
+Render template files into the virtual files tree object.
+
+## postProcessFiles
+
+- **Arguments**
+  - `{FileMiddleware} cb` - file middleware
+
+- **Usage**:
+Push a file middleware that will be applied after all normal file middlewares have been applied.
+
+## onCreateComplete
+
+- **Arguments**
+  - `{function} cb`
+
+- **Usage**:
+Push a callback to be called when the files have been written to disk.
+
+## exitLog
+
+- **Arguments**
+  - `{} msg` - string or value to print after the generation is completed;
+  - `{('log'|'info'|'done'|'warn'|'error')} [type='log']` - type of the message.
+
+- **Usage**:
+Add a message to be printed when the generator exits (after any other standard messages).
+
+## genJSConfig
+
+- **Arguments**
+  - `{any} value`
+
+- **Usage**:
+Convenience method for generating a JS config file from JSON
+
+## injectImports
+
+- **Arguments**
+  - `{string} file` - target file to add imports
+  - `{string | [string]} imports` - imports string/array
+
+- **Usage**:
+Add import statements to a file.
+
+## injectRootOptions
+
+- **Arguments**
+  - `{string} file` - target file to add options
+  - `{string | [string]} options` - options string/array
+
+- **Usage**:
+Add options to the root Vue instance (detected by `new Vue`).
+
+## entryFile
+
+- **Returns**
+  - `{('src/main.ts'|'src/main.js')}`
+
+- **Usage**:
+Get the entry file taking into account typescript.
+
+## invoking
+
+- **Returns**
+  - `{boolean}`
+
+- **Usage**:
+Checks if the plugin is being invoked.
+
diff --git a/docs/dev-guide/plugin-api.md b/docs/dev-guide/plugin-api.md
@@ -0,0 +1,112 @@
+# Plugin API
+
+## getCwd
+
+- **Usage**:
+Returns a current working directory
+
+## resolve
+
+- **Arguments**
+  - `{string} path` - relative path from project root
+
+- **Returns**
+  - `{string}`- the resolved absolute path
+
+- **Usage**:
+Resolve a path for the current project
+
+## hasPlugin
+
+- **Arguments**
+  - `{string} id` - plugin id, can omit the (@vue/|vue-|@scope/vue)-cli-plugin- prefix
+
+- **Returns**
+  - `{boolean}`
+
+- **Usage**:
+Check if the project has a plugin with given id
+
+## registerCommand
+
+- **Arguments**
+  - `{string} name`
+  - `{object} [opts]`
+  ```js
+  {
+    description: string,
+    usage: string,
+    options: { [string]: string }
+  }
+  ```
+  - `{function} fn`
+  ```js
+  (args: { [string]: string }, rawArgs: string[]) => ?Promise
+  ```
+
+- **Usage**:
+Register a command that will become available as `vue-cli-service [name]`.
+
+## chainWebpack
+
+- **Arguments**
+  - `{function} fn`
+
+- **Usage**:
+Register a function that will receive a chainable webpack config. This function is lazy and won't be called until `resolveWebpackConfig` is called.
+
+
+## configureWebpack
+
+- **Arguments**
+  - `{object | function} fn`
+
+- **Usage**:
+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
+that will be merged into the webpack config.
+
+## configureDevServer
+
+- **Arguments**
+  - `{object | function} fn`
+
+- **Usage**:
+Register a dev serve config function. It will receive the express `app` instance of the dev server.
+
+## resolveWebpackConfig
+
+- **Arguments**
+  - `{ChainableWebpackConfig} [chainableConfig]`
+- **Returns**
+  - `{object}` - raw webpack config
+
+- **Usage**:
+Resolve the final raw webpack config, that will be passed to webpack.
+
+## resolveChainableWebpackConfig
+
+- **Returns**
+  - `{ChainableWebpackConfig}`
+
+- **Usage**:
+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.
+
+See [https://github.com/mozilla-neutrino/webpack-chain](https://github.com/mozilla-neutrino/webpack-chain)
+
+## genCacheConfig
+
+- **Arguments**
+  - `id`
+  - `partialIdentifier`
+  - `configFiles`
+- **Returns**
+  - `{object}`
+  ```js
+  {
+    cacheDirectory: string,
+    cacheIdentifier: string }
+  ```
+
+- **Usage**:
+Generate a cache identifier from a number of variables.
+