Skip to content

Commit 3b05d44

Browse files
antfuantfu
authored
docs: move to docs site
1 parent 8a986c2 commit 3b05d44

File tree

1 file changed

+4
-296
lines changed

1 file changed

+4
-296
lines changed

‎README.md

+4-296
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# unplugin
1+
# Unplugin
22

33
[![npm version][npm-version-src]][npm-version-href]
44
[![npm downloads][npm-downloads-src]][npm-downloads-href]
@@ -13,303 +13,11 @@ Currently supports:
1313
- [Webpack](https://webpack.js.org/)
1414
- [esbuild](https://esbuild.github.io/)
1515
- [Rspack](https://www.rspack.dev/) (⚠️ experimental)
16+
- And every framework built on top of them.
1617

17-
## Hooks
18+
## Documentations
1819

19-
`unplugin` extends the excellent [Rollup plugin API](https://rollupjs.org/guide/en/#plugins-overview) as the unified plugin interface and provides a compatible layer base on the build tools used with.
20-
21-
###### Supported
22-
23-
| Hook | Rollup | Vite | Webpack 4 | Webpack 5 | esbuild | Rspack |
24-
| ----------------------------------------------------------------------- | :-------------: | :--: | :-------: | :-------: | :-------------: | :----: |
25-
| [`enforce`](https://rollupjs.org/guide/en/#enforce) | ❌ <sup>1</sup> | ✅ | ✅ | ✅ | ❌ <sup>1</sup> | ✅ |
26-
| [`buildStart`](https://rollupjs.org/guide/en/#buildstart) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
27-
| [`resolveId`](https://rollupjs.org/guide/en/#resolveid) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
28-
| `loadInclude`<sup>2</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
29-
| [`load`](https://rollupjs.org/guide/en/#load) | ✅ | ✅ | ✅ | ✅ | ✅ <sup>3</sup> | ✅ |
30-
| `transformInclude`<sup>2</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
31-
| [`transform`](https://rollupjs.org/guide/en/#transformers) | ✅ | ✅ | ✅ | ✅ | ✅ <sup>3</sup> | ✅ |
32-
| [`watchChange`](https://rollupjs.org/guide/en/#watchchange) | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
33-
| [`buildEnd`](https://rollupjs.org/guide/en/#buildend) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
34-
| [`writeBundle`](https://rollupjs.org/guide/en/#writebundle)<sup>4</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
35-
36-
1. Rollup and esbuild do not support using `enforce` to control the order of plugins. Users need to maintain the order manually.
37-
2. Webpack's id filter is outside of loader logic; an additional hook is needed for better perf on Webpack. In Rollup and Vite, this hook has been polyfilled to match the behaviors. See for the following usage examples.
38-
3. Although esbuild can handle both JavaScript and CSS and many other file formats, you can only return JavaScript in `load` and `transform` results.
39-
4. Currently, `writeBundle` is only serves as a hook for the timing. It doesn't pass any arguments.
40-
41-
> **Warning**: The [Rspack](https://www.rspack.dev/) support is experimental. Future changes to Rspack integrations might not follow semver, please pin `unplugin` in your dependency when using. It's not recommended to use in production.
42-
43-
### Hook Context
44-
45-
###### Supported
46-
47-
| Hook | Rollup | Vite | Webpack 4 | Webpack 5 | esbuild | Rspack |
48-
| -------------------------------------------------------------------------- | :----: | :--: | :-------: | :-------: | :------------: | :----: |
49-
| [`this.parse`](https://rollupjs.org/guide/en/#thisparse) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
50-
| [`this.addWatchFile`](https://rollupjs.org/guide/en/#thisaddwatchfile) | ✅ | ✅ | ✅<sup>6</sup> | ✅ | ✅<sup>7</sup> | ❌ |
51-
| [`this.emitFile`](https://rollupjs.org/guide/en/#thisemitfile)<sup>5</sup> | ✅ | ✅ | ✅<sup>6</sup> | ✅ | ✅ | ✅ |
52-
| [`this.getWatchFiles`](https://rollupjs.org/guide/en/#thisgetwatchfiles) | ✅ | ✅ | ✅<sup>6</sup> | ✅ | ✅<sup>7</sup> | ❌ |
53-
| [`this.warn`](https://rollupjs.org/guide/en/#thiswarn) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
54-
| [`this.error`](https://rollupjs.org/guide/en/#thiserror) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
55-
56-
5. Currently, [`this.emitFile`](https://rollupjs.org/guide/en/#thisemitfile) only supports the `EmittedAsset` variant.
57-
6. Currently, in Webpack, [`this.addWatchFile`](https://rollupjs.org/guide/en/#thisgetwatchfiles), [`this.emitFile`](https://rollupjs.org/guide/en/#thisemitfile), and [`this.getWatchFiles`](https://rollupjs.org/guide/en/#thisgetwatchfiles) are not supported within `resolveId` hooks.
58-
7. Currently, in esbuild, [`this.addWatchFile`](https://rollupjs.org/guide/en/#thisgetwatchfiles) and [`this.getWatchFiles`](https://rollupjs.org/guide/en/#thisgetwatchfiles) are supported only within `resolveId`, `load`, and `transform` hooks; and [`this.getWatchFiles`](https://rollupjs.org/guide/en/#thisgetwatchfiles) returns an array of only the files explicitly watched via [`this.addWatchFile`](https://rollupjs.org/guide/en/#thisaddwatchfile) during the same resolve step (`resolveId` hook) or load step (`load` and `transform` hooks).
59-
60-
## Usage
61-
62-
```ts
63-
import { createUnplugin } from 'unplugin'
64-
65-
export const unplugin = createUnplugin((options: UserOptions) => {
66-
return {
67-
name: 'unplugin-prefixed-name',
68-
// webpack's id filter is outside of loader logic,
69-
// an additional hook is needed for better perf on webpack
70-
transformInclude(id) {
71-
return id.endsWith('.vue')
72-
},
73-
// just like rollup transform
74-
transform(code) {
75-
return code.replace(/<template>/, '<template><div>Injected</div>')
76-
},
77-
// more hooks coming
78-
}
79-
})
80-
81-
export const vitePlugin = unplugin.vite
82-
export const rollupPlugin = unplugin.rollup
83-
export const webpackPlugin = unplugin.webpack
84-
export const rspackPlugin = unplugin.rspack
85-
export const esbuildPlugin = unplugin.esbuild
86-
```
87-
88-
## Nested Plugins
89-
90-
Since `v0.10.0`, unplugin supports constructing multiple nested plugins to behave like a single one. For example:
91-
92-
###### Supported
93-
94-
| Rollup | Vite | Webpack 4 | Webpack 5 | Rspack | esbuild |
95-
| :--------------------: | :--: | :-------: | :-------: | :----: | :------------: |
96-
| ✅ `>=3.1`<sup>6</sup> | ✅ | ✅ | ✅ | ✅ | ⚠️<sup>7</sup> |
97-
98-
6. Rollup supports nested plugins since [v3.1.0](https://github.com/rollup/rollup/releases/tag/v3.1.0). Plugin author should ask users to have a Rollup version of `>=3.1.0` when using nested plugins. For single plugin format, unplugin works for any version of Rollup.
99-
7. Since esbuild does not have a built-in transform phase, the `transform` hook of the nested plugin will not work on esbuild yet. Other hooks like `load` or `resolveId` work fine. We will try to find a way to support it in the future.
100-
101-
###### Usage
102-
103-
```ts
104-
import { createUnplugin } from 'unplugin'
105-
106-
export const unplugin = createUnplugin((options: UserOptions) => {
107-
return [
108-
{
109-
name: 'plugin-a',
110-
transform(code) {
111-
// ...
112-
},
113-
},
114-
{
115-
name: 'plugin-b',
116-
resolveId(id) {
117-
// ...
118-
},
119-
},
120-
]
121-
})
122-
```
123-
124-
## Plugin Installation
125-
126-
###### Vite
127-
128-
```ts
129-
// vite.config.ts
130-
import UnpluginFeature from './unplugin-feature'
131-
132-
export default {
133-
plugins: [
134-
UnpluginFeature.vite({ /* options */ }),
135-
],
136-
}
137-
```
138-
139-
###### Rollup
140-
141-
```ts
142-
// rollup.config.js
143-
import UnpluginFeature from './unplugin-feature'
144-
145-
export default {
146-
plugins: [
147-
UnpluginFeature.rollup({ /* options */ }),
148-
],
149-
}
150-
```
151-
152-
###### Webpack
153-
154-
```ts
155-
// webpack.config.js
156-
module.exports = {
157-
plugins: [
158-
require('./unplugin-feature').webpack({ /* options */ }),
159-
],
160-
}
161-
```
162-
163-
###### esbuild
164-
165-
```ts
166-
// esbuild.config.js
167-
import { build } from 'esbuild'
168-
169-
build({
170-
plugins: [
171-
require('./unplugin-feature').esbuild({ /* options */ }),
172-
],
173-
})
174-
```
175-
176-
###### Rspack
177-
178-
```ts
179-
// rspack.config.js
180-
module.exports = {
181-
plugins: [
182-
require('./unplugin-feature').rspack({ /* options */ }),
183-
],
184-
}
185-
```
186-
187-
### Framework-specific Logic
188-
189-
While `unplugin` provides compatible layers for some hooks, the functionality of it is limited to the common subset of the build's plugins capability. For more advanced framework-specific usages, `unplugin` provides an escape hatch for that.
190-
191-
```ts
192-
export const unplugin = createUnplugin((options: UserOptions, meta) => {
193-
console.log(meta.framework) // 'vite' | 'rollup' | 'webpack' | 'rspack' | 'esbuild'
194-
195-
return {
196-
// Common unplugin hooks
197-
name: 'unplugin-prefixed-name',
198-
transformInclude(id) { /* ... */ },
199-
transform(code) { /* ... */ },
200-
201-
// Framework specific hooks
202-
vite: {
203-
// Vite plugin
204-
configureServer(server) {
205-
// configure Vite server
206-
},
207-
// ...
208-
},
209-
rollup: {
210-
// Rollup plugin
211-
},
212-
webpack(compiler) {
213-
// Configure Webpack compiler
214-
},
215-
rspack(compiler) {
216-
// Configure Rspack compiler
217-
},
218-
esbuild: {
219-
// Change the filter of onResolve and onLoad
220-
// onResolveFilter?: RegExp,
221-
// onLoadFilter?: RegExp,
222-
223-
// Tell esbuild how to interpret the contents. By default unplugin tries to guess the loader
224-
// from file extension (eg: .js -> "js", .jsx -> 'jsx')
225-
// loader?: (Loader | (code: string, id: string) => Loader)
226-
227-
// Read and/or modify build.initialOptions
228-
// [https://esbuild.github.io/plugins/#build-options]
229-
// config?: (initialOptions: BuildOptions) => void
230-
231-
// Or you can completely replace the setup logic
232-
// setup?: EsbuildPlugin.setup,
233-
},
234-
}
235-
})
236-
```
237-
238-
### Creating platform specific plugins
239-
240-
The package exports a set of functions in place of `createUnplugin` that allow for the creation of plugins for specific bundlers.
241-
Each of the function takes the same generic factory argument as `createUnplugin`.
242-
243-
```ts
244-
import {
245-
createEsbuildPlugin,
246-
createRollupPlugin,
247-
createRspackPlugin,
248-
createVitePlugin,
249-
createWebpackPlugin
250-
} from 'unplugin'
251-
252-
const vitePlugin = createVitePlugin({ /* options */ })
253-
const rollupPlugin = createRollupPlugin({ /* options */ })
254-
const esbuildPlugin = createEsbuildPlugin({ /* options */ })
255-
const webpackPlugin = createWebpackPlugin({ /* options */ })
256-
const rspackPlugin = createRspackPlugin({ /* options */ })
257-
```
258-
259-
## Conventions
260-
261-
- Plugins powered by unplugin should have a clear name with `unplugin-` prefix.
262-
- Include `unplugin` keyword in `package.json`.
263-
- To provide better DX, packages could export 2 kinds of entry points:
264-
265-
- Default export: the returned value of `createUnplugin` function
266-
267-
```ts
268-
import UnpluginFeature from 'unplugin-feature'
269-
```
270-
271-
- Subpath exports: properties of the returned value of `createUnplugin` function for each framework users
272-
273-
```ts
274-
import VitePlugin from 'unplugin-feature/vite'
275-
```
276-
277-
- Refer to [unplugin-starter](https://github.com/unplugin/unplugin-starter) for more details about this setup.
278-
279-
## Starter Templates
280-
281-
- [unplugin/unplugin-starter](https://github.com/unplugin/unplugin-starter)
282-
- [jwr12135/create-unplugin](https://github.com/jwr12135/create-unplugin)
283-
- [sxzz/unplugin-starter](https://github.com/sxzz/unplugin-starter)
284-
285-
## Community Showcases
286-
287-
> We have started a GitHub organization to host and collaborate on popular unplugin plugins: [github.com/unplugin](https://github.com/unplugin). You can go there to find more plugins or even join us with your own plugins!
288-
289-
- [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import)
290-
- [unplugin-vue2-script-setup](https://github.com/antfu/unplugin-vue2-script-setup)
291-
- [unplugin-icons](https://github.com/antfu/unplugin-icons)
292-
- [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components)
293-
- [unplugin-upload-cdn](https://github.com/zenotsai/unplugin-upload-cdn)
294-
- [unplugin-web-ext](https://github.com/jwr12135/unplugin-web-ext)
295-
- [unplugin-properties](https://github.com/pd4d10/unplugin-properties)
296-
- [unplugin-moment-to-dayjs](https://github.com/1247748612/unplugin-moment-to-dayjs)
297-
- [unplugin-object-3d](https://github.com/m0ksem/unplugin-object-3d)
298-
- [unplugin-parcel-css](https://github.com/ssssota/unplugin-parcel-css)
299-
- [unplugin-vue](https://github.com/sxzz/unplugin-vue)
300-
- [unplugin-vue-macros](https://github.com/sxzz/unplugin-vue-macros)
301-
- [unplugin-vue-define-options](https://github.com/sxzz/unplugin-vue-macros/tree/main/packages/define-options)
302-
- [unplugin-jsx-string](https://github.com/sxzz/unplugin-jsx-string)
303-
- [unplugin-ast](https://github.com/sxzz/unplugin-ast)
304-
- [unplugin-element-plus](https://github.com/element-plus/unplugin-element-plus)
305-
- [unplugin-glob](https://github.com/sxzz/unplugin-glob)
306-
- [unplugin-sentry](https://github.com/kricsleo/unplugin-sentry)
307-
- [unplugin-imagemin](https://github.com/ErKeLost/unplugin-imagemin)
308-
- [unplugin-typedotenv](https://github.com/ssssota/typedotenv)
309-
- [unplugin-fonts](https://github.com/cssninjaStudio/unplugin-fonts)
310-
- [sentry-javascript-bundler-plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins)
311-
- [unplugin-svg-component](https://github.com/Jevon617/unplugin-svg-component)
312-
- [unplugin-vue-cssvars](https://github.com/baiwusanyu-c/unplugin-vue-cssvars)
20+
Learn more on the [Documentation](https://unplugin.vercel.app/)
31321

31422
## License
31523

0 commit comments

Comments
 (0)