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
- Rollup and esbuild do not support using
enforce
to control the order of plugins. Users need to maintain the order manually. - 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.
- Although esbuild can handle both JavaScript and CSS and many other file formats, you can only return JavaScript in
load
and transform
results.
Hook Context
Supported
- Currently,
this.emitFile
only supports the EmittedAsset
variant.
Usage
import { createUnplugin } from 'unplugin'
export const unplugin = createUnplugin((options: UserOptions) => {
return {
name: 'unplugin-prefixed-name',
transformInclude (id) {
return id.endsWith('.vue')
},
transform (code) {
return code.replace(/<template>/, `<template><div>Injected</div>`)
},
}
})
export const vitePlugin = unplugin.vite
export const rollupPlugin = unplugin.rollup
export const webpackPlugin = unplugin.webpack
export const esbuildPlugin = unplugin.esbuild
Plugin Installation
Vite
import UnpluginFeature from './unplugin-feature'
export default {
plugins: [
UnpluginFeature.vite({ })
]
}
Rollup
import UnpluginFeature from './unplugin-feature'
export default {
plugins: [
UnpluginFeature.rollup({ })
]
}
Webpack
module.exports = {
plugins: [
require('./unplugin-feature').webpack({ })
]
}
esbuild
import { build } from 'esbuild'
build({
plugins: [
require('./unplugin-feature').esbuild({ })
]
})
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)
return {
name: 'unplugin-prefixed-name',
transformInclude (id) { },
transform (code) { },
vite: {
configureServer(server) {
}
},
rollup: {
},
webpack(compiler) {
},
esbuild: {
onResolveFilter?: RegExp
onLoadFilter?: RegExp
setup?: EsbuildPlugin['setup']
}
}
})
Conventions
- Plugins powered by unplugin should have a clear name with
unplugin-
prefix. - Include
unplugin
keyword in package.json
. - To provide better DX, packages could export 2 kinds of entry points:
-
Default export: the returned value of createUnplugin
function
import UnpluginFeature from 'unplugin-feature'
-
Subpath exports: properties of the returned value of createUnplugin
function for each framework users
import VitePlugin from 'unplugin-feature/vite'
-
Refer to unplugin-starter for more details about this setup.
Starter Templates
Examples
License
MIT License © 2021 Nuxt Contrib