Vue Components Auto-Importer

Common errors

• 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.

  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.
  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

  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.
  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.

  cause 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.

Warnings

• breaking 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.
  Fix: Review the `unplugin` v3 changelog and update any custom `unplugin` configurations or integrations accordingly.
• breaking 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.
  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.
• breaking 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.
  Fix: Upgrade your Node.js environment to version 20.19.0 or newer.
• breaking 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.
  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`).
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install unplugin-vue-components npm
• yarn add unplugin-vue-components yarn
• pnpm add unplugin-vue-components pnpm

Imports

• Components
  wrong:

  const Components = require('unplugin-vue-components/vite')

  correct:

  import Components from '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
  wrong:

  const Components = require('unplugin-vue-components/rollup')

  correct:

  import Components from '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
  wrong:

  const Components = require('unplugin-vue-components/webpack')

  correct:

  import Components from '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.

Quickstart

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[\\/]/]
    })
  ]
});