{"id":12313,"library":"unplugin-vue-components","title":"Vue Components Auto-Importer","description":"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.","status":"active","version":"32.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/unplugin/unplugin-vue-components","tags":["javascript","typescript"],"install":[{"cmd":"npm install unplugin-vue-components","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-vue-components","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-vue-components","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for Vue.js projects.","package":"vue","optional":false},{"reason":"Required for Nuxt integration, specifically if using the plugin with Nuxt. Note: Nuxt users often prefer `@nuxt/components`.","package":"@nuxt/kit","optional":true}],"imports":[{"note":"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`).","wrong":"const Components = require('unplugin-vue-components/vite')","symbol":"Components","correct":"import Components from 'unplugin-vue-components/vite'"},{"note":"For Rollup projects. Since v31.0.0, the library is ESM-only. Ensure your Rollup configuration file is an ESM file.","wrong":"const Components = require('unplugin-vue-components/rollup')","symbol":"Components","correct":"import Components from 'unplugin-vue-components/rollup'"},{"note":"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`.","wrong":"const Components = require('unplugin-vue-components/webpack')","symbol":"Components","correct":"import Components from 'unplugin-vue-components/webpack'"},{"note":"Example resolver import for popular UI libraries. Many other resolvers are available, check the documentation for specific library support.","symbol":"ElementPlusResolver","correct":"import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport Components from 'unplugin-vue-components/vite';\nimport { ElementPlusResolver } from 'unplugin-vue-components/resolvers';\n\nexport default defineConfig({\n  plugins: [\n    vue(),\n    Components({\n      // Specify a path to automatically scan components (e.g., your local `src/components` folder)\n      dirs: ['src/components'],\n      // Automatically register components from popular UI libraries using resolvers\n      resolvers: [\n        ElementPlusResolver(), // Example: auto-import Element Plus components\n        // Add other resolvers as needed, e.g., AntDesignVueResolver(), VantResolver(), etc.\n      ],\n      // Generate `components.d.ts` global type declarations for TypeScript support\n      dts: true,\n      // Allow use of `defineOptions` and `defineModels` within components (Vue 3.3+)\n      allowAsProps: true,\n      // Custom transformers (e.g., for custom directives or specific component patterns)\n      transformers: [],\n      // Filter for files that should be processed by the plugin\n      include: [/\\.vue$/, /\\u005c.vue\\u005c?vue/],\n      // Exclude files/directories to avoid processing (e.g., node_modules, build outputs)\n      exclude: [/[\\\\/]node_modules[\\\\/]/, /[\\\\/]\\u005c.git[\\\\/]/, /[\\\\/]\\u005c.nuxt[\\\\/]/]\n    })\n  ]\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Review the `unplugin` v3 changelog and update any custom `unplugin` configurations or integrations accordingly.","message":"Version 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.","severity":"breaking","affected_versions":">=32.0.0"},{"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.","message":"Since 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.","severity":"breaking","affected_versions":">=31.0.0"},{"fix":"Upgrade your Node.js environment to version 20.19.0 or newer.","message":"Version 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.","severity":"breaking","affected_versions":">=31.0.0"},{"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`).","message":"Version 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.","severity":"breaking","affected_versions":">=31.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=29.0.0"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"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.","error":"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."},{"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.","cause":"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.","error":"TypeError [ERR_INVALID_ARG_TYPE]: The 'path' argument must be of type string. Received undefined"},{"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.","cause":"Running `unplugin-vue-components` version 31.0.0 or higher on an unsupported Node.js version.","error":"Error: Node.js version 16.x.x is not supported. Please upgrade to Node.js 20.19.0 or higher."}],"ecosystem":"npm"}