# unplugin-vue-components
On-demand components auto importing for Vue.
###### Features
- Supports Vue 3 out-of-the-box.
- ✨ Supports both components and directives.
- ⚡️ Supports Vite, Webpack, Rspack, Rollup, Rolldown, esbuild and more, powered by
unplugin.
- Tree-shakable, only registers the components you use.
- Folder names as namespaces.
- Full TypeScript support.
- [Built-in resolvers](#importing-from-ui-libraries) for popular UI libraries.
- Works perfectly with [unplugin-icons](https://github.com/antfu/unplugin-icons).
## Installation
```bash
npm i unplugin-vue-components -D
```
> **`vite-plugin-components` has been renamed to `unplugin-vue-components`**, see the [migration guide](#migrate-from-vite-plugin-components).
Vite
```ts
// vite.config.ts
import Components from 'unplugin-vue-components/vite'
export default defineConfig({
plugins: [
Components({ /* options */ }),
],
})
```
Rollup
```ts
// rollup.config.js
import Components from 'unplugin-vue-components/rollup'
export default {
plugins: [
Components({ /* options */ }),
],
}
```
Rolldown
```ts
// rolldown.config.js
import Components from 'unplugin-vue-components/rolldown'
export default {
plugins: [
Components({ /* options */ }),
],
}
```
Webpack
```ts
// webpack.config.js
// unplugin-vue-components removed support for CommonJS after version 29.1.0
module.exports = {
/* ... */
plugins: [
require('unplugin-vue-components/webpack')({ /* options */ }),
],
}
```
Rspack
```ts
// rspack.config.js
// unplugin-vue-components removed support for CommonJS after version 29.1.0
module.exports = {
/* ... */
plugins: [
require('unplugin-vue-components/rspack')({ /* options */ }),
],
}
```
Nuxt
You might not need this plugin for Nuxt. Use [`@nuxt/components`](https://github.com/nuxt/components) instead.
Quasar
```ts
// vite.config.js [Vite]
import Components from 'unplugin-vue-components/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
Components({ /* options */ })
]
})
```
```ts
// quasar.config.js
export default defineConfig(() => {
return {
build: {
vitePlugins: [
['unplugin-vue-components/vite', { /* options */ }],
]
},
}
})
```
esbuild
```ts
// esbuild.config.js
import { build } from 'esbuild'
import Components from 'unplugin-vue-components/esbuild'
build({
/* ... */
plugins: [
Components({
/* options */
}),
],
})
```
## Usage
Use components in templates as you would usually do, it will import components on demand, and there is no `import` and `component registration` required anymore! If you register the parent component asynchronously (or lazy route), the auto-imported components will be code-split along with their parent.
It will automatically turn this
```html
```
into this
```html
```
> **Note**
> By default this plugin will import components in the `src/components` path. You can customize it using the `dirs` option.
## TypeScript
To get TypeScript support for auto-imported components, there is [a PR](https://github.com/vuejs/core/pull/3399) to Vue 3 extending the interface of global components. Currently, [Volar](https://github.com/johnsoncodehk/volar) has supported this usage already. If you are using Volar, you can change the config as following to get the support.
```ts
Components({
dts: true, // enabled by default if `typescript` is installed
})
```
Once the setup is done, a `components.d.ts` will be generated and updates automatically with the type definitions. Feel free to commit it into git or not as you want.
> **Make sure you also add `components.d.ts` to your `tsconfig.json` under `include`.**
## Importing from UI Libraries
We have several built-in resolvers for popular UI libraries like **Vuetify**, **Ant Design Vue**, and **Element Plus**, where you can enable them by:
Supported Resolvers:
- [Ant Design Vue](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/antdv.ts)
- [Arco Design Vue](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/arco.ts)
- [BootstrapVue](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/bootstrap-vue.ts)
- [Element Plus](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/element-plus.ts)
- [Headless UI](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/headless-ui.ts)
- [IDux](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/idux.ts)
- [Inkline](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/inkline.ts)
- [Ionic](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/ionic.ts)
- [Naive UI](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/naive-ui.ts)
- [Prime Vue](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/prime-vue.ts)
- [Quasar](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/quasar.ts)
- [TDesign](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/tdesign.ts)
- [`@tdesign-vue-next/auto-import-resolver`](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/auto-import-resolver/README.md) - TDesign's own auto-import resolver
- [Vant](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/vant.ts)
- [`@vant/auto-import-resolver`](https://github.com/youzan/vant/blob/main/packages/vant-auto-import-resolver/README.md) - Vant's own auto-import resolver
- [Varlet UI](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/varlet-ui.ts)
- [`@varlet/import-resolver`](https://github.com/varletjs/varlet/blob/dev/packages/varlet-import-resolver/README.md) - Varlet's own auto-import resolver
- [VEUI](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/veui.ts)
- [View UI](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/view-ui.ts)
- [Vuetify](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/vuetify.ts) — Prefer first-party plugins when possible: [v3 + vite](https://www.npmjs.com/package/vite-plugin-vuetify), [v3 + webpack](https://www.npmjs.com/package/webpack-plugin-vuetify), [v2 + webpack](https://npmjs.com/package/vuetify-loader)
- [VueUse Components](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/vueuse.ts)
- [VueUse Directives](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/vueuse-directive.ts)
- [Dev UI](https://github.com/antfu/unplugin-vue-components/blob/main/src/core/resolvers/devui.ts)
```ts
import {
AntDesignVueResolver,
ElementPlusResolver,
VantResolver,
} from 'unplugin-vue-components/resolvers'
// vite.config.js
import Components from 'unplugin-vue-components/vite'
// your plugin installation
Components({
resolvers: [
AntDesignVueResolver(),
ElementPlusResolver(),
VantResolver(),
],
})
```
You can also write your own resolver quickly:
```ts
Components({
resolvers: [
// example of importing Vant
(componentName) => {
// where `componentName` is always CapitalCase
if (componentName.startsWith('Van'))
return { name: componentName.slice(3), from: 'vant' }
},
],
})
```
> [We no longer accept new resolvers](./src/core/resolvers/_READ_BEFORE_CONTRIBUTE.md).
## Types for global registered components
Some libraries might register some global components for you to use anywhere (e.g. Vue Router provides `` and ``). Since they are global available, there is no need for this plugin to import them. However, those are commonly not TypeScript friendly, and you might need to register their types manually.
Thus `unplugin-vue-components` provided a way to only register types for global components.
```ts
Components({
dts: true,
types: [{
from: 'vue-router',
names: ['RouterLink', 'RouterView'],
}],
})
```
So the `RouterLink` and `RouterView` will be presented in `components.d.ts`.
By default, `unplugin-vue-components` detects supported libraries automatically (e.g. `vue-router`) when they are installed in the workspace. If you want to disable it completely, you can pass an empty array to it:
```ts
Components({
// Disable type only registration
types: [],
})
```
## Migrate from `vite-plugin-components`
`package.json`
```diff
{
"devDependencies": {
- "vite-plugin-components": "*",
+ "unplugin-vue-components": "^0.14.0",
}
}
```
`vite.config.js`
```
…
```
## Configuration
The following show the default values of the configuration
```
…
```
## Example
[Vitesse](https://github.com/antfu/vitesse) starter template.
## Thanks
Thanks to [@brattonross](https://github.com/brattonross), this project is heavily inspired by [vite-plugin-voie](https://github.com/vamplate/vite-plugin-voie).
## License
[MIT](./LICENSE) License © 2020-PRESENT [Anthony Fu](https://github.com/antfu)