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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy