unplugin-vue-components: on-demand component auto-import for Vue 3

The boilerplate it deletes, and the projects that feel it most

Every Vue single-file component normally pays two taxes: an import statement at the top of the script block and an entry in the components option. The README shows the before and after directly. A template containing `<HelloWorld msg="Hello Vue 3.0 + Vite" />` with an empty script block is rewritten to include `import HelloWorld from './src/components/HelloWorld.vue'` plus a components registration. The plugin performs that edit during the build, so the source file on disk never changes.

The people who feel this most are teams using a large UI library. Importing Element Plus or Ant Design Vue component by component by hand is tedious, and forgetting one produces a runtime warning rather than a compile error, which is the worst kind of failure to debug. The plugin ships resolvers for Ant Design Vue, Arco Design Vue, BootstrapVue, Element Plus, Headless UI, IDux, Inkline, Ionic, Naive UI, Prime Vue, Quasar, TDesign, Vant and Varlet UI. That list is the product's real surface area; the template rewriting is almost incidental once a resolver is in play.

It is not aimed at Nuxt users. The README is explicit: "You might not need this plugin for Nuxt. Use @nuxt/components instead." Take that at face value rather than adding a second auto-import layer on top of the framework's own.

How the build-time rewrite actually works

The project is built on unplugin, which is why the same core is exposed through separate entry points: `./vite`, `./webpack`, `./rspack`, `./rollup`, `./rolldown`, `./esbuild`, `./nuxt`, plus `./resolvers` and `./types`. Each bundler gets a thin adapter over the same transform.

The transform inspects the template portion of a Vue SFC, collects the component tags it finds, and resolves each one against two sources: the local directories (by default `src/components`, configurable through the `dirs` option) and any resolvers you have enabled. A match produces an injected import and a registration entry in the script block. Unmatched tags are left alone, which is why unknown elements do not break the build, they simply fall through to Vue's own resolution and its runtime warning.

Two details shape the architecture more than the marketing does. First, chokidar is a runtime dependency, so the plugin watches the component directories and keeps its internal index current during dev. Second, magic-string is used to make the edits, which is a sign the transform is a surgical string splice rather than a full AST reprint; that keeps it fast and keeps your formatting intact. It also means the injected code is only as good as the tag-matching heuristics, and dynamic component names (`<component :is="...">`) are not something a static scan can resolve.

Installing it in a Vite project and getting a first auto-import

Install as a dev dependency. The package is published on npm as `unplugin-vue-components`, and the README notes it was renamed from `vite-plugin-components`, so old tutorials using that name are describing the same project under its previous identity.

npm i unplugin-vue-components -D

Then register the Vite entry point in the config. Note the import path ends in `/vite`, not the bare package name.

// vite.config.ts
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  plugins: [
    Components({ /* options */ }),
  ],
})

With that in place, drop a `.vue` file into `src/components` and reference it in any template without importing it. The README's example is `<HelloWorld msg="Hello Vue 3.0 + Vite" />`, and the plugin turns it into an import of `./src/components/HelloWorld.vue` plus a components registration. If you register the parent lazily, the README states the auto-imported components are code-split along with their parent.

For TypeScript, enable the declaration output and add the generated file to your tsconfig include list. The README says `dts` is enabled by default when `typescript` is installed, but making it explicit costs nothing.

Components({
  dts: true, // enabled by default if `typescript` is installed
})

That produces `components.d.ts`, which updates automatically. Whether you commit it is left to you; the README says either is fine. What is not optional is the include entry, since the generated file is what teaches Volar about the global components.

Where it stops being the right tool

The most concrete limitation is the CommonJS cut. The Webpack and Rspack examples both carry the same note: unplugin-vue-components removed support for CommonJS after version 29.1.0. If your build pipeline is still CJS, you are pinned below that line or you are rewriting the config. That is a real migration decision, not a footnote.

The second limitation is the generated declaration file. It is a build artifact that lives in your source tree, and the README has to warn you to add it to `tsconfig.json` under `include`. Forget that step and the plugin still works at runtime while your editor reports every auto-imported component as unknown. The failure is silent in the build and loud in the IDE, which sends people looking in the wrong place.

The third is scope. A static template scan cannot see components chosen at runtime through `<component :is>`, and it cannot help with anything outside a Vue template. If your components are resolved dynamically, or if you are not writing Vue 3 templates, the plugin has nothing to rewrite. The peer dependency on `vue: ^3.0.0` makes that boundary explicit.

Finally, the README does not document rollback, nor does it describe what happens to the generated `components.d.ts` when you remove the plugin. Treat removing it as a manual cleanup: delete the plugin from the config, delete the declaration file, and remove the tsconfig include entry.

unplugin-auto-import is the sibling, not the substitute

The related search terms put `unplugin-auto-import` next to this project constantly, and the confusion is understandable because both are unplugin-based build-time injectors from the same ecosystem. The difference is what gets injected.

unplugin-vue-components handles component and directive tags in templates. It reads the template, matches tag names against your `src/components` directory and your resolvers, and injects imports plus component registration. unplugin-auto-import handles the script block: composables and APIs such as `ref` or `computed` that you would otherwise import from `vue` or a utility module. One rewrites markup, the other rewrites code.

They compose rather than compete, and a project can reasonably run both. The practical distinction when you are debugging: a missing component import is a template problem and belongs to this plugin, while an undefined function inside `<script setup>` is a script problem and belongs to auto-import. Enabling the wrong one and waiting for a fix wastes an afternoon.

The README also notes the plugin works with unplugin-icons, which is a third unplugin in the same family. That is worth knowing because icon components are exactly the kind of thing you do not want to import by hand, and the combination is a supported path rather than something you assemble yourself.

Maintenance, release cadence and what MIT means here

The repository is not archived. The last push was on 2026-05-20, and the most recent release, v32.1.0, is dated the same day. Before that, v32.0.0 and v31.1.0 both landed on 2026-03-23, so the pattern in the release list is a major or minor bump roughly every two months rather than a continuous trickle. That is a normal cadence for a build plugin whose surface follows the bundlers it targets.

The version number is worth reading before you upgrade. Going from v31 to v32 is a major bump, and the project has already demonstrated a willingness to make breaking cuts: dropping CommonJS after 29.1.0 is exactly that kind of change. Pin the version in your lockfile and read the changelog before moving across a major boundary.

The runtime floor is Node >=20.19.0, stated in `engines`. That is not a suggestion; older Node will fail the install check under a strict package manager. The licence is MIT, which is permissive and places few obligations on how you redistribute the plugin as part of a build. It does not tell you anything about the licences of the UI libraries your resolvers pull in, and those are separate packages with their own terms. Nothing here is legal advice; if you ship a bundled application commercially, the licences that matter are the ones on the components actually bundled into your output.

Editorial conclusion

Adopt it if your Vue 3 app already leans on a component library and you want per-component imports without writing them by hand; the built-in resolvers for Element Plus, Ant Design Vue, Naive UI, Vant and the rest are the reason to pick this over a hand-written import script. Skip it if you are on Nuxt (the README points to @nuxt/components), if you still need CommonJS output, or if your build must not depend on a generated .d.ts that you can forget to add to tsconfig.json. Verify two things before committing: that your Node version satisfies engines (>=20.19.0) and that components.d.ts is listed under include in tsconfig.json, because without it the auto-imported names stay invisible to the type checker.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. unplugin/unplugin-vue-components on GitHub