unplugin
Unified plugin system for build tools.
Currently supports:
Hooks
unplugin
extends the excellent Rollup plugin API as the unified plugin interface and provides a compatible layer base on the build tools used with.
Supported
Hook | Rollup | Vite | Webpack 4 | Webpack 5 | esbuild |
---|---|---|---|---|---|
buildStart |
|||||
buildEnd |
|||||
transformInclude 1 |
|||||
transform |
|||||
enforce |
|||||
resolveId |
|||||
load |
|||||
watchChange |
- 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 following usage examples.
- Rollup and esbuild do not support using
enforce
to control the order of plugins. Users need to maintain the order manually. - Although esbuild can handle both JavaScript and CSS and many other file formats, you can only return JavaScript in
load
andtransform
results.
Hook Context
Supported
Hook | Rollup | Vite | Webpack 4 | Webpack 5 | esbuild |
---|---|---|---|---|---|
this.parse |
|||||
this.addWatchFile |
|||||
this.emitFile 4 |
|||||
this.getWatchFiles |
|||||
this.warn |
|||||
this.errror |
- Currently,
this.emitFile
only supports theEmittedAsset
variant.
Usage
import { createUnplugin } from 'unplugin'
export const unplugin = createUnplugin((options: UserOptions) => {
return {
name: 'my-first-unplugin',
// webpack's id filter is outside of loader logic,
// an additional hook is needed for better perf on webpack
transformInclude (id) {
return id.endsWith('.vue')
},
// just like rollup transform
transform (code) {
return code.replace(/<template>/, `<template><div>Injected</div>`)
},
// more hooks coming
}
})
export const vitePlugin = unplugin.vite
export const rollupPlugin = unplugin.rollup
export const webpackPlugin = unplugin.webpack
export const esbuildPlugin = unplugin.esbuild
Plugin Installation
Vite
// vite.config.ts
import MyUnplugin from './my-unplugin'
export default {
plugins: [
MyUnplugin.vite({ /* options */ })
]
}
Rollup
// rollup.config.js
import MyUnplugin from './my-unplugin'
export default {
plugins: [
MyUnplugin.rollup({ /* options */ })
]
}
Webpack
// webpack.config.js
module.exports = {
plugins: [
require('./my-unplugin').webpack({ /* options */ })
]
}
esbuild
// esbuild.config.js
import { build } from 'esbuild'
build({
plugins: [
require('./my-unplugin').esbuild({ /* options */ })
]
})
Framework-specific Logic
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.
export const unplugin = createUnplugin((options: UserOptions, meta) => {
console.log(meta.framework) // 'vite' | 'rollup' | 'webpack' | 'esbuild'
return {
// common unplugin hooks
name: 'my-first-unplugin',
transformInclude (id) { /* ... */ },
transform (code) { /* ... */ },
// framework specific hooks
vite: {
// Vite config
configureServer(server) {
// configure Vite server
}
},
rollup: {
// Rollup config
},
webpack(compiler) {
// configure Webpack compiler
},
esbuild: {
// change the filter of onResolve and onLoad
onResolveFilter?: RegExp
onLoadFilter?: RegExp
// or you can completely replace the setup logic
setup?: EsbuildPlugin['setup']
}
}
})
Starter Templates
Examples
- unplugin-auto-import
- unplugin-vue2-script-setup
- unplugin-icons
- unplugin-vue-components
- unplugin-upload-cdn
- unplugin-web-ext
- unplugin-properties
- unplugin-moment-to-dayjs
- unplugin-object-3d
- unplugin-parcel-css
License
MIT License © 2021 Nuxt Contrib