unjs/unplugin

This is stars and forks stats for /unjs/unplugin repository. As of 23 Apr, 2024 this repository has 2505 stars and 82 forks.

unplugin Unified plugin system for build tools. Currently supports: Vite Rollup Webpack esbuild Rspack (⚠️ experimental) 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 Rspack enforce ❌ 1 ✅ ✅ ✅ ❌ 1 ✅ buildStart ✅ ✅ ✅ ✅ ✅ ✅ resolveId ✅ ✅ ✅ ✅ ✅ ❌ loadInclude2 ✅ ✅ ✅ ✅ ✅ ✅ load ✅ ✅ ✅ ✅ ✅ 3 ✅ transformInclude2 ✅ ✅ ✅ ✅ ✅ ✅ transform ✅ ✅ ✅ ✅ ✅ 3 ✅ watchChange ✅ ✅ ✅ ✅ ❌ ❌ buildEnd ✅ ✅ ✅ ✅ ✅ ✅ writeBundle4 ✅ ✅ ✅ ✅ ✅ ✅ 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 the 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. Currently, writeBundle is only serves as a hook for the timing. It doesn't pass any arguments. Warning: The Rspack 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. Hook Context Supported Hook Rollup Vite Webpack 4 Webpack 5 esbuild Rspack this.parse ✅ ✅ ✅ ✅ ✅ ✅ this.addWatchFile ✅ ✅ ✅ ✅ ❌ ❌ this.emitFile5 ✅ ✅ ✅ ✅ ✅ ✅ this.getWatchFiles ✅ ✅ ✅ ✅ ❌ ❌ this.warn ✅ ✅ ✅ ✅ ✅ ✅ this.error ✅ ✅ ✅ ✅ ✅ ✅ Currently, this.emitFile only supports the EmittedAsset variant. Usage import { createUnplugin } from 'unplugin' export const unplugin = createUnplugin((options: UserOptions) => { return { name: 'unplugin-prefixed-name', // 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 rspackPlugin = unplugin.rspack export const esbuildPlugin = unplugin.esbuild Nested Plugins Since v0.10.0, unplugin supports constructing multiple nested plugins to behave like a single one. For example: Supported Rollup Vite Webpack 4 Webpack 5 Rspack esbuild ✅ >=3.16 ✅ ✅ ✅ ✅ ⚠️7 Rollup supports nested plugins since 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. 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. Usage import { createUnplugin } from 'unplugin' export const unplugin = createUnplugin((options: UserOptions) => { return [ { name: 'plugin-a', transform(code) { // ... }, }, { name: 'plugin-b', resolveId(id) { // ... }, }, ] }) Plugin Installation Vite // vite.config.ts import UnpluginFeature from './unplugin-feature' export default { plugins: [ UnpluginFeature.vite({ /* options */ }), ], } Rollup // rollup.config.js import UnpluginFeature from './unplugin-feature' export default { plugins: [ UnpluginFeature.rollup({ /* options */ }), ], } Webpack // webpack.config.js module.exports = { plugins: [ require('./unplugin-feature').webpack({ /* options */ }), ], } esbuild // esbuild.config.js import { build } from 'esbuild' build({ plugins: [ require('./unplugin-feature').esbuild({ /* options */ }), ], }) Rspack // rspack.config.js module.exports = { plugins: [ require('./unplugin-feature').rspack({ /* 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' | 'rspack' | 'esbuild' return { // Common unplugin hooks name: 'unplugin-prefixed-name', transformInclude(id) { /* ... */ }, transform(code) { /* ... */ }, // Framework specific hooks vite: { // Vite plugin configureServer(server) { // configure Vite server }, // ... }, rollup: { // Rollup plugin }, webpack(compiler) { // Configure Webpack compiler }, rspack(compiler) { // Configure Rspack compiler }, esbuild: { // Change the filter of onResolve and onLoad // onResolveFilter?: RegExp, // onLoadFilter?: RegExp, // Tell esbuild how to interpret the contents. By default unplugin tries to guess the loader // from file extension (eg: .js -> "js", .jsx -> 'jsx') // loader?: (Loader | (code: string, id: string) => Loader) // Or you can completely replace the setup logic // setup?: EsbuildPlugin.setup, }, } }) Creating platform specific plugins The package exports a set of functions in place of createUnplugin that allow for the creation of plugins for specific bundlers. Each of the function takes the same generic factory argument as createUnplugin. import { createEsbuildPlugin, createRollupPlugin, createRspackPlugin, createVitePlugin, createWebpackPlugin } from 'unplugin' const vitePlugin = createVitePlugin({ /* options */ }) const rollupPlugin = createRollupPlugin({ /* options */ }) const esbuildPlugin = createEsbuildPlugin({ /* options */ }) const webpackPlugin = createWebpackPlugin({ /* options */ }) const rspackPlugin = createRspackPlugin({ /* options */ }) 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 unplugin/unplugin-starter jwr12135/create-unplugin sxzz/unplugin-starter Community Showcases We have started a GitHub organization to host and collaborate on popular unplugin plugins: github.com/unplugin. You can go there to find more plugins or even join us with your own plugins! 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 unplugin-vue unplugin-vue-macros unplugin-vue-define-options unplugin-jsx-string unplugin-ast unplugin-element-plus unplugin-glob unplugin-sentry unplugin-imagemin unplugin-typedotenv unplugin-fonts sentry-javascript-bundler-plugins unplugin-svg-component unplugin-vue-cssvars License MIT License © 2021-PRESENT Nuxt Contrib