Skip to content

Commit 3b20f33

Browse files
antfuantfu
committed
docs: update readme
1 parent e0e5c63 commit 3b20f33

File tree

1 file changed

+130
-68
lines changed

1 file changed

+130
-68
lines changed

‎README.md

Lines changed: 130 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1-
<h2 align='center'><samp>unplugin-vue-components</samp></h2>
1+
# unplugin-vue-components
22

3-
<p align='center'>On-demand components auto importing for Vue.<br><sub>Works for Vite, Webpack, Vue CLI and more, powered by <a href="https://github.com/unjs/unplugin">unplugin</a></sub></p>
3+
[![NPM version](https://img.shields.io/npm/v/unplugin-vue-components?color=a1b858&label=)](https://www.npmjs.com/package/unplugin-vue-components)
44

5-
<p align='center'>
6-
<a href='https://www.npmjs.com/package/unplugin-vue-components'>
7-
<img src='https://img.shields.io/npm/v/unplugin-vue-components?color=222&style=flat-square'>
8-
</a>
9-
</p>
5+
On-demand components auto importing for Vue.
6+
7+
###### Features
8+
9+
- 💚 Supports both Vue 2 and Vue 3 out-of-the-box.
10+
- ⚡️ Supports Vite, Webpack, Vue CLI, rollup and more, powered by <a href="https://github.com/unjs/unplugin">unplugin</a>.
11+
- 🏝 Tree-shakable, only registers the components you use.
12+
- 🪐 Folder as namespaces.
13+
- 🦾 Full TypeScript support.
14+
- 🌈 [Built-in resolvers](#importing-from-ui-libraries) for popular UI libraries.
15+
- 😃 Works perfectly with [unplugin-icons](https://github.com/antfu/unplugin-icons).
1016

1117
<br>
1218

@@ -18,30 +24,84 @@
1824

1925
<br>
2026

21-
## Usage
22-
23-
Install
27+
## Installation
2428

2529
```bash
2630
npm i unplugin-vue-components -D
2731
```
2832

29-
Add it to `vite.config.js`
33+
<details>
34+
<summary>Vite</summary><br>
3035

3136
```ts
32-
// vite.config.js
33-
import Vue from '@vitejs/plugin-vue'
37+
// vite.config.ts
3438
import Components from 'unplugin-vue-components/vite'
3539

40+
export default defineConfig({
41+
plugins: [
42+
Components({ /* options */ }),
43+
],
44+
})
45+
```
46+
47+
<br></details>
48+
49+
<details>
50+
<summary>Rollup</summary><br>
51+
52+
```ts
53+
// rollup.config.js
54+
import Components from 'unplugin-vue-components/rollup'
55+
3656
export default {
3757
plugins: [
38-
Vue(),
39-
Components()
58+
Components({ /* options */ }),
4059
],
41-
};
60+
}
61+
```
62+
63+
<br></details>
64+
65+
66+
<details>
67+
<summary>Webpack</summary><br>
68+
69+
```ts
70+
// webpack.config.js
71+
module.exports = {
72+
/* ... */
73+
plugins: [
74+
require('unplugin-vue-components/webpack')({ /* options */ })
75+
]
76+
}
4277
```
4378

44-
That's all.
79+
<br></details>
80+
81+
<details>
82+
<summary>Nuxt</summary><br>
83+
84+
You don't need this plugin for Nuxt, use [`@nuxt/components`](https://github.com/nuxt/components) instead.
85+
86+
<br></details>
87+
88+
<details>
89+
<summary>Vue CLI</summary><br>
90+
91+
```ts
92+
// vue.config.js
93+
module.exports = {
94+
configureWebpack: {
95+
plugins: [
96+
require('unplugin-vue-components/webpack')({ /* options */ }),
97+
],
98+
},
99+
}
100+
```
101+
102+
<br></details>
103+
104+
## Usage
45105

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

@@ -82,69 +142,20 @@ export default {
82142
</script>
83143
```
84144

85-
## Migrate from `vite-plugin-components`
86-
87-
`package.json`
88-
89-
```diff
90-
{
91-
"devDependencies": {
92-
- "vite-plugin-components": "*",
93-
+ "unplugin-vue-components": "^0.14.0",
94-
}
95-
}
96-
```
97-
98-
`vite.config.json`
99-
100-
```diff
101-
- import Components, { ElementPlusResolver } from 'vite-plugin-components'
102-
+ import Components from 'unplugin-vue-components/vite'
103-
+ import ElementPlusResolver from 'unplugin-vie-components/resolvers'
104-
105-
export default {
106-
plugins: [
107-
/* ... */
108-
Components({
109-
resolvers: [
110-
ElementPlusResolver(),
111-
]
112-
}),
113-
],
114-
}
115-
```
116-
117145
## TypeScript
118146

119147
To have TypeScript support for auto-imported components, there is [a PR](https://github.com/vuejs/vue-next/pull/3399) to Vue 3 extending the interface of global components. Currently, [Volar](https://github.com/johnsoncodehk/volar) has supported this usage already, if you are using Volar, you can change the config as following to get the support.
120148

121149
```ts
122150
Components({
123-
dts: true, // enabled by default if `typescript is installed
151+
dts: true, // enabled by default if `typescript` is installed
124152
})
125153
```
126154

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

129157
**Make sure you also add `components.d.ts` to your `tsconfig.json` under `includes`.**
130158

131-
## Vue 2 Support
132-
133-
It just works.
134-
135-
```ts
136-
// vite.config.js
137-
import { createVuePlugin as Vue2 } from 'vite-plugin-vue2'
138-
import Components from 'unplugin-vue-components/vite'
139-
140-
export default {
141-
plugins: [
142-
Vue2(),
143-
Components(),
144-
],
145-
}
146-
```
147-
148159
## Importing from UI Libraries
149160

150161
We have several built-in resolvers for popular UI libraries like **Vuetify**, **Ant Design Vue**, and **Element Plus**, where you can enable them by:
@@ -199,6 +210,51 @@ Components({
199210

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

213+
214+
## Migrate from `vite-plugin-components`
215+
216+
`package.json`
217+
218+
```diff
219+
{
220+
"devDependencies": {
221+
- "vite-plugin-components": "*",
222+
+ "unplugin-vue-components": "^0.14.0",
223+
}
224+
}
225+
```
226+
227+
`vite.config.json`
228+
229+
```diff
230+
- import Components, { ElementPlusResolver } from 'vite-plugin-components'
231+
+ import Components from 'unplugin-vue-components/vite'
232+
+ import ElementPlusResolver from 'unplugin-vie-components/resolvers'
233+
234+
export default {
235+
plugins: [
236+
/* ... */
237+
Components({
238+
/* ... */
239+
240+
// `customComponentsResolvers` has renamed to `resolver`
241+
- customComponentsResolvers: [
242+
+ resolvers: [
243+
ElementPlusResolver(),
244+
],
245+
246+
// `globalComponentsDeclaration` has renamed to `dts`
247+
- globalComponentsDeclaration: true,
248+
+ dts: true,
249+
250+
// `customLoaderMatcher` is depreacted, use `include` instead
251+
- customLoaderMatcher: id => id.endsWith('.md'),
252+
+ include: [/\.vue$/, /\.vue\?vue&type=template/, /\.md$/],
253+
}),
254+
],
255+
}
256+
```
257+
202258
## Configuration
203259

204260
The following show the default values of the configuration
@@ -212,6 +268,8 @@ Components({
212268
extensions: ['vue'],
213269
// search for subdirectories
214270
deep: true,
271+
// resolvers for custom components
272+
resolvers: [],
215273

216274
// generate `components.d.ts` global declrations,
217275
// also accepts a path for custom filename
@@ -222,6 +280,10 @@ Components({
222280
// Subdirectory paths for ignoring namespace prefixes
223281
// works when `directoryAsNamespace: true`
224282
globalNamespaces: [],
283+
284+
// filters for transforming targets
285+
include: [/\.vue$/, /\.vue\?vue&type=template/],
286+
exclude: [/node_modules/, /\.git/, /\.nuxt/],
225287
})
226288
```
227289

@@ -235,4 +297,4 @@ Thanks to [@brattonross](https://github.com/brattonross), this project is heavil
235297

236298
## License
237299

238-
MIT License © 2020 [Anthony Fu](https://github.com/antfu)
300+
MIT License © 2020-PRESENT [Anthony Fu](https://github.com/antfu)

0 commit comments

Comments
 (0)