Plugins and Presets
Plugins
Vue CLI uses a plugin-based architecture. If you inspect a newly created project's package.json
, you will find dependencies that start with @vue/cli-plugin-
. Plugins can modify the internal webpack configuration and inject commands to vue-cli-service
. Most of the features listed during the project creation process are implemented as plugins.
The plugin based architecture makes Vue CLI flexible and extensible. If you are interested in developing a plugin, check out the Plugin Development Guide.
You can install and manage Plugins using the GUI with the vue ui
command.
Installing Plugins in an Existing Project
Each CLI plugin ships with a generator (which creates files) and a runtime plugin (which tweaks the core webpack config and injects commands). When you use vue create
to create a new project, some plugins will be pre-installed for you based on your feature selection. In case you want to install a plugin into an already created project, you can do so with the vue add
command:
vue add eslint
vue add
is specifically designed for installing and invoking Vue CLI plugins. It is not meant as a replacement for normal npm packages. For normal npm packages, you should still use your package manager of choice.
It is recommended to commit your project's current state before running vue add
, since the command will invoke the plugin's file generator and potentially make changes to your existing files.
The command resolves @vue/eslint
to the full package name @vue/cli-plugin-eslint
, installs it from npm, and invokes its generator.
# these are equivalent to the previous usage
vue add cli-plugin-eslint
Without the @vue
prefix, the command will resolve to an unscoped package instead. For example, to install the 3rd party plugin vue-cli-plugin-apollo
:
# installs and invokes vue-cli-plugin-apollo
vue add apollo
You can also use 3rd party plugins under a specific scope. For example, if a plugin is named @foo/vue-cli-plugin-bar
, you can add it with:
vue add @foo/bar
You can pass generator options to the installed plugin (this will skip the prompts):
vue add eslint --config airbnb --lintOn save
vue-router
and vuex
are special cases - they do not have their own plugins, but you can add them nonetheless:
vue add router
vue add vuex
If a plugin is already installed, you can skip the installation and only invoke its generator with the vue invoke
command. The command takes the same arguments as vue add
.
If for some reason your plugins are listed in a package.json
file other than the one located in your project, you can set the vuePlugins.resolveFrom
option in the project package.json
with the path to the folder containing the other package.json
file.
For example, if you have a .config/package.json
file:
{
"vuePlugins": {
"resolveFrom": ".config"
}
}
Project local plugin
If you need access to the plugin API in your project and don't want to create a full plugin for it, you can use the vuePlugins.service
option in your package.json
file:
{
"vuePlugins": {
"service": ["my-commands.js"]
}
}
Each file will need to export a function taking the plugin API as the first argument. For more information about the plugin API, check out the Plugin Development Guide.
You can also add files that will behave like UI plugins with the vuePlugins.ui
option:
{
"vuePlugins": {
"ui": ["my-ui.js"]
}
}
For more information, read the UI Plugin API.
Presets
A Vue CLI preset is a JSON object that contains pre-defined options and plugins for creating a new project so that the user doesn't have to go through the prompts to select them.
Presets saved during vue create
are stored in a configuration file in your user home directory (~/.vuerc
). You can directly edit this file to tweak / add / delete the saved presets.
Here's an example preset:
{
"useConfigFiles": true,
"router": true,
"vuex": true,
"cssPreprocessor": "sass",
"plugins": {
"@vue/cli-plugin-babel": {},
"@vue/cli-plugin-eslint": {
"config": "airbnb",
"lintOn": ["save", "commit"]
}
}
}
The preset data is used by plugin generators to generate corresponding project files. In addition to the above fields, you can also add additional configuration for integrated tools:
{
"useConfigFiles": true,
"plugins": {...},
"configs": {
"vue": {...},
"postcss": {...},
"eslintConfig": {...},
"jest": {...}
}
}
These additional configurations will be merged into package.json
or corresponding config files, depending on the value of useConfigFiles
. For example, with "useConfigFiles": true
, the value of configs.vue
will be merged into vue.config.js
.
Preset Plugin Versioning
You can explicitly specify versions of the plugins being used:
{
"plugins": {
"@vue/cli-plugin-eslint": {
"version": "^3.0.0",
// ... other options for this plugin
}
}
}
Note this is not required for official plugins - when omitted, the CLI will automatically use the latest version available in the registry. However, it is recommended to provide a explicit version range for any 3rd party plugins listed in a preset.
Allowing Plugin Prompts
Each plugin can inject its own prompts during the project creation process, however when you are using a preset, those prompts will be skipped because Vue CLI assumes all the plugin options are already declared in the preset.
In some cases you may want the preset to only declare the desired plugins, while leaving some flexibility by letting the user go through the prompts injected by the plugins.
For such scenarios you can specify "prompts": true
in a plugin's options to allow its prompts to be injected:
{
"plugins": {
"@vue/cli-plugin-eslint": {
// let the users pick their own ESLint config
"prompts": true
}
}
}
Remote Presets
You can share a preset with other developers by publishing it in a git repo. The repo can contain the following files:
preset.json
: the main file containing the preset data (required).generator.js
: a Generator that can inject or modify files in the project.prompts.js
: a prompts file that can collect options for the generator.
Once the repo is published, you can then use the --preset
option to use the remote preset when creating a project:
# use preset from GitHub repo
vue create --preset username/repo my-project
GitLab and BitBucket are also supported. Make sure to use the --clone
option if fetching from private repos:
vue create --preset gitlab:username/repo --clone my-project
vue create --preset bitbucket:username/repo --clone my-project
# self-hosted repos
vue create --preset gitlab:my-gitlab-server.com:group/projectname --clone my-project
vue create --preset direct:ssh://git@my-gitlab-server.com/group/projectname.git --clone my-project
Local Filesystem Preset
When developing a remote preset, it can be tedious to have to repeatedly push the preset to a remote repo to test it. To simplify the workflow, you can directly work with local presets. Vue CLI will load local presets if the value for the --preset
option is a relative or absolute file path, or ends with .json
:
# ./my-preset should be a directory containing preset.json
vue create --preset ./my-preset my-project
# or directly use a json file in cwd:
vue create --preset my-preset.json my-project