unplugin

library3.0.0jsnpmunverified

Unplugin is a unified plugin system designed to abstract away the differences between various JavaScript build tools, allowing developers to write a single plugin that works across multiple bundlers. As of its current stable version, `3.0.0`, it supports major tools like Vite, Rollup, Webpack, esbuild, Rspack, Rolldown, Farm, and Bun. The project maintains an active development pace with frequent updates and bug fixes, typically releasing minor versions as features are added and major versions when significant breaking changes or architectural shifts occur, as seen with the recent v3.0.0. Its primary differentiator is eliminating the need to adapt plugin logic for each build tool's specific API, providing a consistent hook-based interface that simplifies cross-bundler compatibility and reduces development overhead for library authors and application builders. It ships with full TypeScript support, ensuring a robust developer experience.

devops

npm install unplugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNPLUGIN

unplugin

devopsjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createUnplugin

✓ import { createUnplugin } from 'unplugin'

✗ const { createUnplugin } = require('unplugin')

Unplugin v3.0.0 is ESM-only; CommonJS `require` is no longer supported.

UnpluginFactory

✓ import type { UnpluginFactory } from 'unplugin'

Type import for defining a plugin factory function in TypeScript.

vitePlugin

✓ import { vitePlugin } from 'unplugin/vite'

✗ import { unplugin } from 'unplugin'; const vitePlugin = unplugin.vite;

Bundler-specific integrations like `.vite` are exposed directly from subpaths for tree-shaking and cleaner imports.

This quickstart demonstrates how to create a simple Unplugin using `createUnplugin` and integrate it into a Vite project to add a banner to processed files.

import { createUnplugin } from 'unplugin'; import { defineConfig } from 'vite'; // plugins/my-banner-plugin.ts export const bannerPlugin = createUnplugin(() => { return { name: 'my-banner-plugin', transformInclude(id) { // Only process .ts and .js files in src directory return id.startsWith('/src/') && (id.endsWith('.ts') || id.endsWith('.js')); }, transform(code) { // Add a simple banner at the top of the file return `/* Powered by Unplugin! */\n${code}`; } }; }); // For Vite integration export const viteBannerPlugin = bannerPlugin.vite; // vite.config.ts (example usage) export default defineConfig({ plugins: [ viteBannerPlugin(), // Call the factory function ] }); // src/main.ts console.log("Hello, Unplugin!"); // After build with Vite, 'src/main.ts' will start with '/* Powered by Unplugin! */'

Debug

Known issues

breakingUnplugin v3.0.0 drops official support for Node.js 18. Running on unsupported Node.js versions may lead to unexpected behavior or errors.

fix

Upgrade your Node.js environment to version `^20.19.0` or `>=22.12.0`.

affects: >=3.0.0

breakingUnplugin v3.0.0 removes its CommonJS (CJS) build. The package is now exclusively ESM, which means `require()` statements will no longer work.

fix

Migrate your project to use ECMAScript Modules (ESM) with `import` statements. Ensure your `package.json` has `"type": "module"` or uses `.mjs` file extensions for ESM files.

affects: >=3.0.0

breakingThe `acorn` dependency has been removed in Unplugin v3.0.0. If your plugin utilizes AST-related hooks, you are now responsible for providing your own parser configuration.

fix

When creating a plugin with `createUnplugin`, you must pass a custom `parser` option to handle AST parsing. For example: `createUnplugin(() => ({ /* ... */ }), { parser: { parse, ... } })` using `acorn` or a compatible parser.

affects: >=3.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use Unplugin v3.x in a CommonJS module context, which is no longer supported.

fix

Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements for `unplugin`.

Error: Minimum Node.js version not met

Running Unplugin v3.x with an unsupported Node.js version, such as Node.js 18.

fix

Upgrade your Node.js runtime to `^20.19.0` or `>=22.12.0` or newer to meet the engine requirements.

[my-plugin] Failed to parse AST: Unexpected token (1:0)

A plugin using AST-related hooks (e.g., `transform`, `resolveId` with AST parsing) fails because `acorn` is no longer bundled, and no custom parser is provided.

fix

Provide a custom parser configuration to `createUnplugin` options. Example: `import * as acorn from 'acorn'; createUnplugin(() => ({ /* ... */ }), { parser: acorn })`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

noderequiredRuntime environment requirement for Unplugin v3.0.0 and above.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/unjs/unplugin ↗

packagehttps://www.npmjs.com/package/unplugin ↗

homepagehttps://unplugin.unjs.io ↗