unplugin-vue-components

Fork notice: this is a fork of unplugin-vue-components published as @xu22web/unplugin-vue-components. It adds Vapor Mode component auto import (vapor: true) on top of the upstream package, everything else is identical. Install it with npm i @xu22web/unplugin-vue-components -D and keep importing from @xu22web/unplugin-vue-components/vite, /resolvers, etc.

On-demand components auto importing for Vue.

Features

💚 Supports Vue 3 out-of-the-box.
✨ Supports both components and directives.
⚡️ Supports Vite, Webpack, Rspack, Rollup, Rolldown, 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 @xu22web/unplugin-vue-components -D

vite-plugin-components has been renamed to unplugin-vue-components, see the migration guide.

Vite

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

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

Rollup

// rollup.config.js
import Components from '@xu22web/unplugin-vue-components/rollup'

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

Rolldown

// rolldown.config.js
import Components from '@xu22web/unplugin-vue-components/rolldown'

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

Webpack

// webpack.config.js
// @xu22web/unplugin-vue-components removed support for CommonJS after version 29.1.0
module.exports = {
  /* ... */
  plugins: [
    require('@xu22web/unplugin-vue-components/webpack')({ /* options */ }),
  ],
}

Rspack

// rspack.config.js
// @xu22web/unplugin-vue-components removed support for CommonJS after version 29.1.0
module.exports = {
  /* ... */
  plugins: [
    require('@xu22web/unplugin-vue-components/rspack')({ /* options */ }),
  ],
}

Nuxt

You might not need this plugin for Nuxt. Use @nuxt/components instead.

Quasar

// vite.config.js [Vite]
import Components from '@xu22web/unplugin-vue-components/vite'
import { defineConfig } from 'vite'

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

// quasar.config.js
export default defineConfig(() => {
  return {
    build: {
      vitePlugins: [
        ['@xu22web/unplugin-vue-components/vite', { /* options */ }],
      ]
    },
  }
})

esbuild

// esbuild.config.js
import { build } from 'esbuild'
import Components from '@xu22web/unplugin-vue-components/esbuild'

build({
  /* ... */
  plugins: [
    Components({
      /* options */
    }),
  ],
})

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>

Note By default this plugin will import components in the src/components path. You can customize it using the dirs option.

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, // enabled by default if `typescript` is installed
})

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

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:

Ant Design Vue
Arco Design Vue
BootstrapVue
Element Plus
Headless UI
IDux
Inkline
Ionic
Naive UI
Prime Vue
Quasar
TDesign
- @tdesign-vue-next/auto-import-resolver - TDesign's own auto-import resolver
Vant
- @vant/auto-import-resolver - Vant's own auto-import resolver
Varlet UI
- @varlet/import-resolver - Varlet's own auto-import resolver
VEUI
View UI
Vuetify — Prefer first-party plugins when possible: v3 + vite, v3 + webpack, v2 + webpack
VueUse Components
VueUse Directives
Dev UI

import {
  AntDesignVueResolver,
  ElementPlusResolver,
  VantResolver,
} from '@xu22web/unplugin-vue-components/resolvers'
// vite.config.js
import Components from '@xu22web/unplugin-vue-components/vite'

// your plugin installation
Components({
  resolvers: [
    AntDesignVueResolver(),
    ElementPlusResolver(),
    VantResolver(),
  ],
})

You can also write your own resolver quickly:

Components({
  resolvers: [
    // example of importing Vant
    (componentName) => {
      // where `componentName` is always CapitalCase
      if (componentName.startsWith('Van'))
        return { name: componentName.slice(3), from: 'vant' }
    },
  ],
})

We no longer accept new resolvers.

Vapor Mode

Vue 3.6's Vapor Mode compiles templates into direct DOM operations. When a template uses a component that can not be statically resolved in the SFC itself (a component of your dirs, or one provided by a resolver such as <el-button>), the Vapor compiler emits _createAssetComponent("el-button", ...), which resolves the component by its name at runtime.

Enable the vapor option so the plugin resolves those components and injects the imports just like it does for the vDOM compiler output:

// vite.config.js
import Vue from '@vitejs/plugin-vue'
import { ElementPlusResolver } from '@xu22web/unplugin-vue-components/resolvers'
import Components from '@xu22web/unplugin-vue-components/vite'

export default {
  plugins: [
    // `features.vapor` forces all SFCs into Vapor Mode,
    // a single file can also opt in with `<script setup vapor>`
    Vue({ features: { vapor: true } }),
    Components({
      vapor: true,
      resolvers: [ElementPlusResolver()],
    }),
  ],
}

features.vapor requires @vitejs/plugin-vue >= 6.0.9, only from that version on the whole project can be compiled in Vapor Mode. With older versions the per-file <script setup vapor> marker has to be used. Note that features.vapor can not force SFCs that only have a plain <script> (Vapor SFCs require <script setup>), they stay vDOM and are rendered through the Vapor <-> vDOM interop.

Only the helper name and the component name are rewritten, everything else is kept as-is, so _createAssetComponent("el-button", props, slots) becomes createComponent(ElButton, props, slots) - the exact same thing the compiler would have generated for an explicit import { ElButton } from 'element-plus'. Components found in dirs/globs are supported too, and they are added to components.d.ts (and .components-info.json) as usual. Server-side rendering is not affected: with ssr: true the Vapor compiler emits the regular _resolveComponent calls, which the plugin has always transformed.

A few things to keep in mind:

Names that the plugin can not resolve are left untouched, so components registered globally on the app instance keep working (with a warning from Vue when they do not exist).
<component :is="..." /> is not covered, the Vapor compiler turns it into createDynamicComponent(), which the plugin can not resolve statically.
Auto imported directives are not handled specially. Vapor emits resolveDirective("...") just like the vDOM compiler does, so the import is still injected, but a directive has to be a function in a Vapor template - Vue skips vDOM object directives (what most resolvers return) with a warning: Received a VDOM object directive in a Vapor template.
The transform depends on the helper name emitted by the Vapor compiler, which is still experimental. If a future Vue version renames it, the components silently fall back to plain elements - run the plugin with the unplugin-vue-components:transform:component debug namespace enabled to see which components were resolved.

A complete fixture (basic, recursive, namespaced, async, markdown, custom resolvers, icons and a UI library) is available in examples/vite-vue3-vapor.

Types for global registered components

Some libraries might register some global components for you to use anywhere (e.g. Vue Router provides <RouterLink> and <RouterView>). Since they are global available, there is no need for this plugin to import them. However, those are commonly not TypeScript friendly, and you might need to register their types manually.

Thus unplugin-vue-components provided a way to only register types for global components.

Components({
  dts: true,
  types: [{
    from: 'vue-router',
    names: ['RouterLink', 'RouterView'],
  }],
})

So the RouterLink and RouterView will be presented in components.d.ts.

By default, unplugin-vue-components detects supported libraries automatically (e.g. vue-router) when they are installed in the workspace. If you want to disable it completely, you can pass an empty array to it:

Components({
  // Disable type only registration
  types: [],
})

Migrate from `vite-plugin-components`

package.json

{
  "devDependencies": {
-   "vite-plugin-components": "*",
+   "@xu22web/unplugin-vue-components": "^0.14.0",
  }
}

vite.config.js

- import Components, { ElementPlusResolver } from 'vite-plugin-components'
+ import Components from '@xu22web/unplugin-vue-components/vite'
+ import { ElementPlusResolver } from '@xu22web/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/, /\.vue\.[tj]sx?\?vue/, /\.md$/],
    }),
  ],
}

Configuration

The following show the default values of the configuration

Components({
  // relative paths to the directory to search for components.
  dirs: ['src/components'],

  // valid file extensions for components.
  extensions: ['vue'],

  // Glob patterns to match file names to be detected as components.
  // You can also specify multiple like this: `src/components/*.{vue,tsx}`
  // When specified, the `dirs`, `extensions`, and `directoryAsNamespace` options will be ignored.
  // If you want to exclude components being registered, use negative globs with leading `!`.
  globs: ['src/components/*.vue'],

  // search for subdirectories
  deep: true,

  // resolvers for custom components
  resolvers: [],

  // generate `components.d.ts` global declarations,
  // also accepts a path for custom filename
  // default: `true` if package typescript is installed
  dts: false,

  // generate dts with TSX support
  // default: `true` if `@vitejs/plugin-vue-jsx` is installed
  dtsTsx: false,

  // Allow subdirectories as namespace prefix for components.
  directoryAsNamespace: false,

  // Collapse same prefixes (camel-sensitive) of folders and components
  // to prevent duplication inside namespaced component name.
  // works when `directoryAsNamespace: true`
  collapseSamePrefixes: false,

  // Subdirectory paths for ignoring namespace prefixes.
  // works when `directoryAsNamespace: true`
  globalNamespaces: [],

  // auto import for directives
  directives: true,

  // enable component auto import for Vue Vapor Mode (Vue 3.6+),
  // see the "Vapor Mode" section above
  vapor: false,

  // Transform path before resolving
  importPathTransform: v => v,

  // Allow for components to override other components with the same name
  allowOverrides: false,

  // Filters for transforming targets (components to insert the auto import)
  // Note these are NOT about including/excluding components registered - use `globs` or `excludeNames` for that
  include: [/\.vue$/, /\.vue\?vue/, /\.vue\.[tj]sx?\?vue/],
  exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]\.nuxt[\\/]/],

  // Filters for component names that will not be imported
  // Use for globally imported async components or other conflicts that the plugin cannot detect
  excludeNames: [/^Async.+/],

  // Vue version of project. It will detect automatically if not specified.
  // Acceptable value: 2 | 2.7 | 3
  version: 2.7,

  // Only provide types of components in library (registered globally)
  // see https://github.com/unplugin/unplugin-vue-components/blob/main/src/core/type-imports/index.ts
  types: [
    /* ... */
  ],

  // Save component information into a JSON file for other tools to consume.
  // Provide a filepath to save the JSON file.
  // When set to `true`, it will save to `./.components-info.json`
  dumpComponentsInfo: false,

  // The mode for syncing the components.d.ts and .components-info.json file.
  // 'append': only append the new components to the existing files.
  // 'overwrite': overwrite the whole existing files with the current components.
  // 'default': use 'append' strategy when using dev server, 'overwrite' strategy when using build.
  syncMode: 'default',
})

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
examples		examples
src		src
test		test
.gitignore		.gitignore
.tazerc.json		.tazerc.json
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts

Navigation Menu

Repository files navigation

unplugin-vue-components

Features

Installation

Usage

TypeScript

Importing from UI Libraries

Vapor Mode

Types for global registered components

Migrate from `vite-plugin-components`

Configuration

Example

Thanks

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

unplugin-vue-components

Features

Installation

Usage

TypeScript

Importing from UI Libraries

Vapor Mode

Types for global registered components

Migrate from vite-plugin-components

Configuration

Example

Thanks

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Migrate from `vite-plugin-components`