Registry / web-framework / unplugin-vue-components

unplugin-vue-components

JSON →
library32.0.0jsnpmunverified

unplugin-vue-components is an unplugin-powered build tool plugin that provides on-demand auto-importing for Vue 3 components and directives. It eliminates the need for manual `import` statements and component registrations, simplifying development workflows and enabling automatic code-splitting for asynchronously loaded parent components. The current stable version is 32.0.0, released in April 2026. The project maintains a frequent release cadence, with minor and patch versions released regularly (often weekly or bi-weekly) and major versions introducing breaking changes every few months. Its key differentiators include broad build tool support (Vite, Webpack, Rollup, Rolldown, esbuild, Rspack) via the `unplugin` ecosystem, tree-shakability, built-in resolvers for popular UI libraries, folder-based namespaces, and full TypeScript support, including generated type declarations. It also integrates well with `unplugin-icons` for icon auto-importing.

npm install unplugin-vue-components
INSTALL
IMPORT
SIG · UNPLUGIN-VUE-COMPO
U
unplugin-vue-components
web-frameworkjavascriptv32.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Components
import Components from 'unplugin-vue-components/vite'
const Components = require('unplugin-vue-components/vite')
For Vite projects. Since v31.0.0, the library is ESM-only. Ensure your `vite.config.ts` or `vite.config.js` is an ESM file (e.g., uses `import`/`export`).
Components
import Components from 'unplugin-vue-components/rollup'
const Components = require('unplugin-vue-components/rollup')
For Rollup projects. Since v31.0.0, the library is ESM-only. Ensure your Rollup configuration file is an ESM file.
Components
import Components from 'unplugin-vue-components/webpack'
const Components = require('unplugin-vue-components/webpack')
For Webpack projects. Since v31.0.0, the library is ESM-only. Webpack configurations often still use CommonJS, requiring careful setup to import ESM packages correctly. Consider using dynamic import `const Components = await import('unplugin-vue-components/webpack')` or converting `webpack.config.js` to `webpack.config.mjs`.
ElementPlusResolver
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
Example resolver import for popular UI libraries. Many other resolvers are available, check the documentation for specific library support.

This quickstart demonstrates configuring `unplugin-vue-components` with Vite and Vue 3, including how to set up component scanning, use UI library resolvers (like Element Plus), and enable TypeScript declaration generation. It also shows common configuration options for directories, inclusions, and exclusions.

import { defineConfig } from 'vite'; import vue from '@vitejs/plugin-vue'; import Components from 'unplugin-vue-components/vite'; import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'; export default defineConfig({ plugins: [ vue(), Components({ // Specify a path to automatically scan components (e.g., your local `src/components` folder) dirs: ['src/components'], // Automatically register components from popular UI libraries using resolvers resolvers: [ ElementPlusResolver(), // Example: auto-import Element Plus components // Add other resolvers as needed, e.g., AntDesignVueResolver(), VantResolver(), etc. ], // Generate `components.d.ts` global type declarations for TypeScript support dts: true, // Allow use of `defineOptions` and `defineModels` within components (Vue 3.3+) allowAsProps: true, // Custom transformers (e.g., for custom directives or specific component patterns) transformers: [], // Filter for files that should be processed by the plugin include: [/\.vue$/, /\u005c.vue\u005c?vue/], // Exclude files/directories to avoid processing (e.g., node_modules, build outputs) exclude: [/[\\/]node_modules[\\/]/, /[\\/]\u005c.git[\\/]/, /[\\/]\u005c.nuxt[\\/]/] }) ] });
Debug
Known issues
breakingVersion 32.0.0 upgrades the underlying `unplugin` dependency to v3. This might introduce breaking changes or require adjustments if you are using advanced `unplugin` features or custom plugins that rely on older `unplugin` APIs.
fix
Review the `unplugin` v3 changelog and update any custom `unplugin` configurations or integrations accordingly.
affects: >=32.0.0
breakingSince version 31.0.0, `unplugin-vue-components` has moved to ESM-only. CommonJS `require()` statements are no longer supported directly. This impacts how the plugin is imported in build tool configuration files, especially for Webpack and Rspack setups which traditionally use CommonJS.
fix
Convert build configuration files (e.g., `webpack.config.js`, `rollup.config.js`) to use ESM syntax (`import`/`export`). For Webpack, consider renaming `.js` to `.mjs` or using dynamic `import()` for the plugin. Ensure your Node.js environment is configured for ESM.
affects: >=31.0.0
breakingVersion 31.0.0 drops support for Node.js versions older than 20.19.0. Running the plugin with an unsupported Node.js version will lead to errors.
fix
Upgrade your Node.js environment to version 20.19.0 or newer.
affects: >=31.0.0
breakingVersion 31.0.0 removes support for Vue 2 and the associated `element-ui` resolver. If your project still uses Vue 2 or relies on `element-ui` auto-importing, this version is not compatible.
fix
For Vue 2 projects, stick to a version prior to 31.0.0. For Vue 3 projects migrating from `element-ui`, switch to `element-plus` and its corresponding resolver (`ElementPlusResolver`).
affects: >=31.0.0
breakingVersion 29.0.0 upgrades the peer dependency `@nuxt/kit` to v4. This is a breaking change for Nuxt users who are not yet on Nuxt 4 or compatible `@nuxt/kit` versions.
fix
Ensure your Nuxt project is updated to a version compatible with `@nuxt/kit` v4, or use a version of `unplugin-vue-components` prior to v29.0.0.
affects: >=29.0.0
gotchaIf you are using Nuxt, you might not need `unplugin-vue-components` directly. Nuxt provides its own component auto-importing feature via `@nuxt/components`, which is often preferred for deeper integration within the Nuxt ecosystem.
fix
For Nuxt projects, consider using `@nuxt/components`. If `unplugin-vue-components` is still desired for specific advanced features, ensure it's configured carefully alongside Nuxt's built-in capabilities to avoid conflicts.
affects: all
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ... is not supported. Instead change the require of ... to a dynamic import() or change the configuration to enable ESM.
Attempting to `require()` `unplugin-vue-components` (or its build tool specific entry points) in a CommonJS context after v31.0.0, when the package became ESM-only.
fix
Update your build configuration file (e.g., `webpack.config.js`, `rollup.config.js`) to use ESM `import` statements or dynamic `import()`. For Webpack, consider renaming your config file to `webpack.config.mjs`.
TypeError [ERR_INVALID_ARG_TYPE]: The 'path' argument must be of type string. Received undefined
This generic error can occur if the `Components` plugin is called without a valid configuration object or if a resolver is misconfigured, leading to internal path resolution issues. Often related to missing `dts` option or incorrect `dirs` path.
fix
Ensure the `Components` plugin is called with an object `Components({ /* options */ })` and that `dts: true` is set if you rely on type generation. Double-check all resolver configurations and component directories for correctness.
Error: Node.js version 16.x.x is not supported. Please upgrade to Node.js 20.19.0 or higher.
Running `unplugin-vue-components` version 31.0.0 or higher on an unsupported Node.js version.
fix
Upgrade your Node.js environment to version 20.19.0 or newer. Use a Node.js version manager like `nvm` to switch versions if needed.
Upgrade
Version history
32.0.0latest on npm
Audit
Dependencies
vuerequiredCore dependency for Vue.js projects.
@nuxt/kitoptionalRequired for Nuxt integration, specifically if using the plugin with Nuxt. Note: Nuxt users often prefer `@nuxt/components`.
Agent activity
2 hits · last 30 days
node
2
Resources
unplugin-vue-components — npm install unplugin-vue-components · libregistry