unplugin

What is unplugin?

The unplugin npm package is a framework-agnostic plugin system designed to create plugins that work across different build tools like Webpack, Vite, Rollup, and more. It allows developers to write a plugin once and have it compatible with multiple build systems without the need to rewrite it for each one.

What are unplugin's main functionalities?

Virtual Modules

Create virtual modules that can be imported by your code. These modules don't exist on the filesystem but are created on the fly by the plugin.

unplugin.createPlugin({
  resolveId(id) {
    if (id === 'virtual-module') return id;
  },
  load(id) {
    if (id === 'virtual-module') return 'export default "This is virtual!"';
  }
});

Transformations

Apply custom transformations to your code. This can be used to modify the source code of files before they are bundled.

unplugin.createPlugin({
  transform(code, id) {
    if (id.endsWith('.custom')) {
      return code.replace(/find/g, 'replace');
    }
  }
});

Custom Build Steps

Execute custom code at different stages of the build process. This can be used to perform tasks before or after the build.

unplugin.createPlugin({
  buildStart() {
    console.log('Build started!');
  },
  buildEnd() {
    console.log('Build finished!');
  }
});

Other packages similar to unplugin

rollup-plugin-replace

A Rollup plugin that allows replacing strings in files while bundling. It's similar to unplugin's transformation feature but is specific to Rollup.

webpack-virtual-modules

A Webpack plugin to add virtual modules to the module graph. It provides functionality similar to unplugin's virtual modules but is specific to Webpack.

vite-plugin-vue2

A Vite-specific plugin to support Vue 2.x. It demonstrates how plugins can be tailored to specific build tools, whereas unplugin aims to be build-tool agnostic.

README

unplugin

Unified plugin system for build tools.

Currently supports:

• Vite
• Rollup
• Webpack
• esbuild

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
enforce	❌ 1	✅	✅	✅	❌ 1
buildStart	✅	✅	✅	✅	✅
resolveId	✅	✅	✅	✅	✅
loadInclude2	✅	✅	✅	✅	✅
load	✅	✅	✅	✅	✅ 3
transformInclude2	✅	✅	✅	✅	✅
transform	✅	✅	✅	✅	✅ 3
watchChange	✅	✅	✅	✅	✅
buildEnd	✅	✅	✅	✅	✅

1. Rollup and esbuild do not support using enforce to control the order of plugins. Users need to maintain the order manually.
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 following usage examples.
3. 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

Hook	Rollup	Vite	Webpack 4	Webpack 5	esbuild
this.parse	✅	✅	✅	✅	✅
this.addWatchFile	✅	✅	✅	✅	✅
this.emitFile4	✅	✅	✅	✅	✅
this.getWatchFiles	✅	✅	✅	✅	✅
this.warn	✅	✅	✅	✅	✅
this.error	✅	✅	✅	✅	✅

1. 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 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	esbuild
✅ >=3.1	✅	✅	✅	⚠️5

1. Since esbuild does not have a built-in transform phase, the transform hook of 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 */ })
  ]
})

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: 'unplugin-prefixed-name',
    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']
    }
  }
})

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-starter
• create-unplugin ^Community

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
• unplugin-vue
• unplugin-vue-macros
• unplugin-vue-define-options
• unplugin-jsx-string
• unplugin-ast
• unplugin-element-plus
• unplugin-glob

License

MIT License © 2021-PRESENT Nuxt Contrib

Changelog

0.10.0 (2022-10-18)

Features

• support nested plugins (#176) (d35e055)