unplugin-vue-components
![NPM version](https://img.shields.io/npm/v/unplugin-vue-components?color=a1b858&label=)
On-demand components auto importing for Vue.
Features
- 💚 Supports both Vue 2 and Vue 3 out-of-the-box.
- ✨ Supports both components and directives.
- ⚡️ Supports Vite, Webpack, Vue CLI, Rollup, esbuild and more, powered by unplugin.
- 🏝 Tree-shakable, only registers the components you use.
- 🪐 Folder names as namespaces.
- 🦾 Full TypeScript support.
- 🌈 Built-in resolvers for popular UI libraries.
- 😃 Works perfectly with unplugin-icons.
Installation
npm i unplugin-vue-components -D
vite-plugin-components
has been renamed to unplugin-vue-components
, see the migration guide.
Vite
import Components from 'unplugin-vue-components/vite'
export default defineConfig({
plugins: [
Components({ }),
],
})
Rollup
import Components from 'unplugin-vue-components/rollup'
export default {
plugins: [
Components({ }),
],
}
Webpack
module.exports = {
plugins: [
require('unplugin-vue-components/webpack')({ })
]
}
Nuxt
You might not need this plugin for Nuxt. Use @nuxt/components
instead.
Vue CLI
module.exports = {
configureWebpack: {
plugins: [
require('unplugin-vue-components/webpack')({ }),
],
},
}
esbuild
import { build } from 'esbuild'
build({
plugins: [
require('unplugin-vue-components/esbuild')({
}),
],
})
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
<template>
<div>
<HelloWorld msg="Hello Vue 3.0 + Vite" />
</div>
</template>
<script>
export default {
name: 'App'
}
</script>
into this
<template>
<div>
<HelloWorld msg="Hello Vue 3.0 + Vite" />
</div>
</template>
<script>
import HelloWorld from './src/components/HelloWorld.vue'
export default {
name: 'App',
components: {
HelloWorld
}
}
</script>
TypeScript
To get TypeScript support for auto-imported components, there is a PR to Vue 3 extending the interface of global components. Currently, Volar has supported this usage already. If you are using Volar, you can change the config as following to get the support.
Components({
dts: true,
})
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 includes
.
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:
import Components from 'unplugin-vue-components/vite'
import {
AntDesignVueResolver,
ElementPlusResolver,
VantResolver,
} from 'unplugin-vue-components/resolvers'
Components({
resolvers: [
AntDesignVueResolver(),
ElementPlusResolver(),
VantResolver(),
]
})
You can also write your own resolver quickly:
Components({
resolvers: [
(name) => {
if (name.startsWith('Van'))
return { importName: name.slice(3), path: 'vant' }
}
]
})
If you successfully configured other UI libraries, please feel free to contribute and help others using them out-of-box. Thanks!
Migrate from vite-plugin-components
package.json
{
"devDependencies": {
- "vite-plugin-components": "*",
+ "unplugin-vue-components": "^0.14.0",
}
}
vite.config.json
- import Components, { ElementPlusResolver } from 'vite-plugin-components'
+ import Components from 'unplugin-vue-components/vite'
+ import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
export default {
plugins: [
/* ... */
Components({
/* ... */
// `customComponentsResolvers` has renamed to `resolver`
- customComponentsResolvers: [
+ resolvers: [
ElementPlusResolver(),
],
// `globalComponentsDeclaration` has renamed to `dts`
- globalComponentsDeclaration: true,
+ dts: true,
// `customLoaderMatcher` is depreacted, use `include` instead
- customLoaderMatcher: id => id.endsWith('.md'),
+ include: [/\.vue$/, /\.vue\?vue/, /\.md$/],
}),
],
}
Configuration
The following show the default values of the configuration
Components({
dirs: ['src/components'],
extensions: ['vue'],
deep: true,
resolvers: [],
dts: false,
directoryAsNamespace: false,
globalNamespaces: [],
directives: true,
include: [/\.vue$/, /\.vue\?vue/],
exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]\.nuxt[\\/]/],
})
Example
See the Vitesse starter template.
Thanks
Thanks to @brattonross, this project is heavily inspired by vite-plugin-voie.
License
MIT License © 2020-PRESENT Anthony Fu