Plugin Development Guide #

Getting started #

A CLI plugin is an npm package that can add additional features to the project using Vue CLI. These features can include:

• changing project webpack config - for example, you can add a new webpack resolve rule for a certain file extension, if your plugin is supposed to work with this type of files. Say, @vue/cli-plugin-typescript adds such rule to resolve .ts and .tsx extensions;
• adding new vue-cli-service command - for example, @vue/cli-plugin-unit-jest adds a new command test:unit that allows developer to run unit tests;
• extending package.json - a useful option when your plugin adds some dependencies to the project and you need to add them to package dependencies section;
• creating new files in the project and/or modifying old ones. Sometimes it's a good idea to create an example component or modify a main file to add some imports;
• prompting user to select certain options - for example, you can ask user if they want to create the example component mentioned above.

CLI Plugin should always contain a Service Plugin as its main export, and can optionally contain a Generator, a Prompt File and a Vue UI integration.

As an npm package, CLI plugin must have a package.json file. It's also recommended to have a plugin description in README.md to help others find your plugin on npm.

So, typical CLI plugin folder structure looks like the following:

.
├── README.md
├── generator.js  # generator (optional)
├── index.js      # service plugin
├── package.json
├── prompts.js    # prompts file (optional)
└── ui.js         # Vue UI integration (optional)

Naming and discoverability #

For a CLI plugin to be usable in a Vue CLI project, it must follow the name convention vue-cli-plugin-<name> or @scope/vue-cli-plugin-<name>. It allows your plugin to be:

• Discoverable by @vue/cli-service;
• Discoverable by other developers via searching;
• Installable via vue add <name> or vue invoke <name>.

For better discoverability when a user searches for your plugin, put keywords describing your plugin in the description field of the plugin package.json file.

Example:

{
  "name": "vue-cli-plugin-apollo",
  "version": "0.7.7",
  "description": "vue-cli plugin to add Apollo and GraphQL"
}

You should add the url to the plugin website or repository in the homepage or repository field so that a 'More info' button will be displayed in your plugin description:

{
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Akryum/vue-cli-plugin-apollo.git"
  },
  "homepage": "https://github.com/Akryum/vue-cli-plugin-apollo#readme"
}

Generator #

A Generator part of the CLI plugin is usually needed when you want to extend your package with new dependencies, create new files in your project or edit existing ones.

Inside the CLI plugin the generator should be placed in a generator.js or generator/index.js file. It will be invoked in two possible scenarios:

• During a project's initial creation, if the CLI plugin is installed as part of the project creation preset.

• When the plugin is installed after project's creation and invoked individually via vue add or vue invoke.

A generator should export a function which receives three arguments:

1. A GeneratorAPI instance;