Vue CLI plug-in and Preset

Plug - ins

The Vue CLI uses a plug-in-based architecture. I f you look at package.json for a newly created project, you'll see that the dependencies all start with @vue/cli-plugin. T he plug-in can modify the internal configuration of the webpack or inject commands into the vue-cli-service. During the creation of the project, most of the features listed are implemented through plug-ins.

Plug-in-based architecture makes the Vue CLI flexible and scalable. If you are interested in developing a plug-in, go through the Plug-in Development Guide.

Tips

You can use the vue ui command to install and manage plug-ins using the GUI.

Install plug-ins in existing projects

Each CLI plug-in contains a generator (for creating files) and a runtime plug-in (for adjusting the core configuration of the webpack and injecting commands). W hen you use vue create to create a new project, some plug-ins are preinstalled based on the features you choose. If you want to install a plug-in in a project that has already been created, you can use the vue add command:

vue add eslint

Tips

Vue add is designed to install and invoke Vue CLI plug-ins. T his does not mean replacing the normal npm package. For these normal npm packages, you still need to choose the package manager.

Warning

We recommend submitting the latest status of the project before running vue add, because the command may call the plug-in's file generator and most likely change your existing files.

This command resolves @vue/eslint to the full package name @vue/cli-plugin-eslint, and then installs it from npm and calls its generator.

# 这个和之前的用法等价
vue add cli-plugin-eslint

If you @vue prefix, the command is replaced with a package that resolves an unscoped. For example, the following command installs a third-party plug-in, vue-cli-plugin-apollo:

# 安装并调用 vue-cli-plugin-apollo
vue add apollo

You can also use third-party plug-ins based on a specified scope. For example, if a plug-in @foo/vue-cli-plugin-bar, you can add it this way:

vue add @foo/bar

You can pass the generator option to the installed plug-in (doing so skips command prompts):

vue add eslint --config airbnb --lintOn save

If a plug-in is already installed, you can use the vue invoke command to skip the installation process and call only its generator. This command accepts the same parameters as vue add.

Tips

If for some reason your plug-in is listed in another package.json file outside of the project, you can set the vuePlugins.resolveFrom option in your own project's package.json to point to a folder that contains other package.json.

For example, if you have a .config/package.json file:

{
  "vuePlugins": {
    "resolveFrom": ".config"
  }
}

The plug-in that is local to the project

If you need direct access to the plug-in API in your project without having to create a full plug-in, you can use the vuePlugins.service option in the package.json file:

{
  "vuePlugins": {
    "service": ["my-commands.js"]
  }
}

Each file needs to expose a function that accepts the plug-in API as the first argument. More information about the Plug-in API can be found in the Plug-in Development Guide.

You can also add files that work like UI plug-ins with the vuePlugins.ui option:

{
  "vuePlugins": {
    "ui": ["my-ui.js"]
  }
}

For more information, read the UI Plug-in API.

Preset

A Vue CLI preset is a JSON object that contains predefined options and plug-ins needed to create a new project, eliminating the need for users to select them in command prompts.

Presets saved during the vue create process are placed in a profile under your home directory (-/.vuerc). You can adjust, add, and delete saved presets by editing the file directly.

Here's an example of a preset:

{
  "useConfigFiles": true,
  "cssPreprocessor": "sass",
  "plugins": {
    "@vue/cli-plugin-babel": {},
    "@vue/cli-plugin-eslint": {
      "config": "airbnb",
      "lintOn": ["save", "commit"]
    },
    "@vue/cli-plugin-router": {},
    "@vue/cli-plugin-vuex": {}
  }
}

Preset's data is used by the plug-in generator to generate the appropriate project files. In addition to these fields, you can also add configurations for integration tools:

{
  "useConfigFiles": true,
  "plugins": {...},
  "configs": {
    "vue": {...},
    "postcss": {...},
    "eslintConfig": {...},
    "jest": {...}
  }
}

These additional configurations will be merged into package.json or the appropriate profile based on the value of useConfigFiles. For example, when "useConfigFiles": true, the value of configs is merged into the vue.config .js file.

Version management of preset plug-ins

You can explicitly specify the version of the plug-in you use:

{
  "plugins": {
    "@vue/cli-plugin-eslint": {
      "version": "^3.0.0",
      // ... 该插件的其它选项
    }
  }
}

Note that this is not necessary for official plug-ins - when ignored, the CLI automatically uses the latest version in registry. However, we recommend that you provide an explicit version range for all third-party plug-ins listed in preset.

The command prompt that allows the plug-in

Each plug-in can inject its own command prompts during project creation, but when you use a preset, those command prompts are skipped because the Vue CLI assumes that all plug-in options have already been declared in the preset.

In some cases, you might want preset to declare only the plug-ins they need, while allowing users to retain some flexibility with the command prompts injected by the plug-ins.

For this scenario you can specify "prompts": true in the plug-in options to allow the injection of command prompts:

{
  "plugins": {
    "@vue/cli-plugin-eslint": {
      // 让用户选取他们自己的 ESLint config
      "prompts": true
    }
  }
}

Remote Preset

You can share a preset with other developers by publishing git repo. This repo should contain the following files:

• preset.json: The primary file (required) that contains the preset data.
• Generator .js: A Generator that can inject or modify Chinese of a project.
• the .js a prompt file that can collect options for generators through a command-line conversation.

After you publish repo, you can use this remote preset with the --preset option when you create the project:

# 从 GitHub repo 使用 preset
vue create --preset username/repo my-project

GitLab and BitBucket are also supported. If you want to get it from a private repo, be sure to use the --clone option:

vue create --preset gitlab:username/repo --clone my-project
vue create --preset bitbucket:username/repo --clone my-project

Load Preset in the file system

When developing a remote preset, you have to go to great pains to issue push to the remote repo for repeated testing. T o simplify this process, you can also test the preset directly locally. If the value of the --preset option is a relative or absolute file path, or ends with .json, the Vue CLI loads the local preset:

# ./my-preset 应当是一个包含 preset.json 的文件夹
vue create --preset ./my-preset my-project

# 或者，直接使用当前工作目录下的 json 文件：
vue create --preset my-preset.json my-project