unplugin-vue-components

What is unplugin-vue-components?

unplugin-vue-components is a plugin for Vue.js that automatically imports Vue components on demand. It helps to reduce the boilerplate code by eliminating the need to manually import components in your Vue files. This plugin supports various component libraries and can be configured to work with custom components as well.

What are unplugin-vue-components's main functionalities?

Automatic Component Import

This feature allows you to automatically import Vue components without having to manually import them in each file. The plugin scans your project and imports the components as needed.

module.exports = {
  plugins: [
    require('unplugin-vue-components/webpack')({
      /* options */
    })
  ]
}

Support for Multiple Component Libraries

This feature allows you to use components from multiple libraries like Element Plus, Vant, etc., without manually importing them. The plugin provides resolvers for various popular libraries.

module.exports = {
  plugins: [
    require('unplugin-vue-components/webpack')({
      resolvers: [
        require('unplugin-vue-components/resolvers').ElementPlusResolver(),
        require('unplugin-vue-components/resolvers').VantResolver()
      ]
    })
  ]
}

Custom Component Directories

You can configure the plugin to automatically import components from custom directories. This is useful for organizing your components in a way that suits your project structure.

module.exports = {
  plugins: [
    require('unplugin-vue-components/webpack')({
      dirs: ['src/components', 'src/custom-components']
    })
  ]
}

Other packages similar to unplugin-vue-components

vite-plugin-components

vite-plugin-components is a Vite plugin that automatically imports Vue components on demand. It is similar to unplugin-vue-components but is specifically designed for Vite, a build tool that aims to provide a faster and leaner development experience for modern web projects.

babel-plugin-import

babel-plugin-import is a Babel plugin for importing components on demand. It is not limited to Vue and can be used with other libraries like Ant Design. It requires more configuration compared to unplugin-vue-components but offers similar functionality.

README

unplugin-vue-components

On-demand components auto importing for Vue.
_{Works for Vite, Webpack, Vue CLI and more, powered by unplugin}

Usage

Install

npm i unplugin-vue-components -D

Add it to vite.config.js

// vite.config.js
import Vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'

export default {
  plugins: [
    Vue(),
    Components()
  ],
};

That's all.

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.

Basically, 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>

Migrate from vite-plugin-components

package.json

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

vite.config.json

- import Components, { ElementPlusResolver } from 'vite-plugin-components'
+ import Components from 'unplugin-vue-components/vite'
+ import ElementPlusResolver from 'unplugin-vie-components/resolvers'

export default {
  plugins: [
    /* ... */
    Components({
      resolvers: [
        ElementPlusResolver(),
      ]
    }),
  ],
}

TypeScript

To have 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 includes.

Vue 2 Support

It just works.

// vite.config.js
import { createVuePlugin as Vue2 } from 'vite-plugin-vue2'
import Components from 'unplugin-vue-components/vite'

export default {
  plugins: [
    Vue2(),
    Components(),
  ],
}

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
• Element Plus
• Headless UI
• Naive UI
• Prime Vue
• Vant
• Varlet UI
• Vuetify
• VueUse Components
• View UI
• Element UI

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

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

You can also write your own resolver easily:

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

If you made other UI libraries configured, please feel free to contribute so it can help others using them out-of-box. Thanks!

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'],
  // search for subdirectories
  deep: true,

  // generate `components.d.ts` global declrations, 
  // also accepts a path for custom filename
  globalComponentsDeclaration: false,

  // Allow subdirectories as namespace prefix for components.
  directoryAsNamespace: false,
  // Subdirectory paths for ignoring namespace prefixes
  // works when `directoryAsNamespace: true`
  globalNamespaces: [],
})

Example

See the Vitesse starter template.

Thanks

Thanks to @brattonross, this project is heavily inspired by vite-plugin-voie.

License

MIT License © 2020 Anthony Fu