{"id":14205,"library":"unplugin","title":"Unplugin Unified Plugin System","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/unplugin","tags":["javascript","typescript"],"install":[{"cmd":"npm install unplugin","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment requirement for Unplugin v3.0.0 and above.","package":"node","optional":false}],"imports":[{"note":"Unplugin v3.0.0 is ESM-only; CommonJS `require` is no longer supported.","wrong":"const { createUnplugin } = require('unplugin')","symbol":"createUnplugin","correct":"import { createUnplugin } from 'unplugin'"},{"note":"Type import for defining a plugin factory function in TypeScript.","symbol":"UnpluginFactory","correct":"import type { UnpluginFactory } from 'unplugin'"},{"note":"Bundler-specific integrations like `.vite` are exposed directly from subpaths for tree-shaking and cleaner imports.","wrong":"import { unplugin } from 'unplugin'; const vitePlugin = unplugin.vite;","symbol":"vitePlugin","correct":"import { vitePlugin } from 'unplugin/vite'"}],"quickstart":{"code":"import { createUnplugin } from 'unplugin';\nimport { defineConfig } from 'vite';\n\n// plugins/my-banner-plugin.ts\nexport const bannerPlugin = createUnplugin(() => {\n  return {\n    name: 'my-banner-plugin',\n    transformInclude(id) {\n      // Only process .ts and .js files in src directory\n      return id.startsWith('/src/') && (id.endsWith('.ts') || id.endsWith('.js'));\n    },\n    transform(code) {\n      // Add a simple banner at the top of the file\n      return `/* Powered by Unplugin! */\\n${code}`;\n    }\n  };\n});\n\n// For Vite integration\nexport const viteBannerPlugin = bannerPlugin.vite;\n\n// vite.config.ts (example usage)\nexport default defineConfig({\n  plugins: [\n    viteBannerPlugin(), // Call the factory function\n  ]\n});\n\n// src/main.ts\nconsole.log(\"Hello, Unplugin!\");\n// After build with Vite, 'src/main.ts' will start with '/* Powered by Unplugin! */'","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version `^20.19.0` or `>=22.12.0`.","message":"Unplugin v3.0.0 drops official support for Node.js 18. Running on unsupported Node.js versions may lead to unexpected behavior or errors.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Unplugin v3.0.0 removes its CommonJS (CJS) build. The package is now exclusively ESM, which means `require()` statements will no longer work.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'3.0.0':40 'abstract':13 'across':31 'activ':59 'ad':75 'adapt':101 'allow':22 'api':110 'applic':132 'architectur':84 'author':130 'away':14 'base':116 'break':81 'bug':66 'build':20,106 'builder':133 'bun':54 'bundler':33,122 'chang':82 'compat':123 'consist':113 'cross':121 'cross-bundl':120 'current':37 'design':11 'develop':23,60,126,143 'differ':16 'differenti':95 'elimin':97 'ensur':140 'esbuild':49 'experi':144 'farm':52 'featur':73 'fix':67 'frequent':63 'full':137 'hook':115 'hook-bas':114 'interfac':117 'javascript':19,145 'librari':129 'like':45 'logic':103 'maintain':57 'major':43,77 'minor':70 'multipl':32 'need':99 'occur':86 'overhead':127 'pace':61 'plugin':3,9,28,102 'primari':94 'project':56 'provid':111 'recent':91 'reduc':125 'releas':69 'robust':142 'rolldown':51 'rollup':47 'rspack':50 'seen':88 'shift':85 'ship':135 'signific':80 'simplifi':119 'singl':27 'specif':109 'stabl':38 'support':42,139 'system':4,10 'tool':21,44,107 'typescript':138,146 'typic':68 'unifi':2,8 'unplugin':1,5 'updat':64 'v3.0.0':92 'various':18 'version':39,71,78 'vite':46 'webpack':48 'work':30 'write':25","created_at":"2026-04-20T01:58:28.721862+00:00","updated_at":"2026-04-20T01:58:28.721862+00:00","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import` statements for `unplugin`.","cause":"Attempting to use Unplugin v3.x in a CommonJS module context, which is no longer supported.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Upgrade your Node.js runtime to `^20.19.0` or `>=22.12.0` or newer to meet the engine requirements.","cause":"Running Unplugin v3.x with an unsupported Node.js version, such as Node.js 18.","error":"Error: Minimum Node.js version not met"},{"fix":"Provide a custom parser configuration to `createUnplugin` options. Example: `import * as acorn from 'acorn'; createUnplugin(() => ({ /* ... */ }), { parser: acorn })`.","cause":"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.","error":"[my-plugin] Failed to parse AST: Unexpected token (1:0)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://unplugin.unjs.io","github":"https://github.com/unjs/unplugin","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/unplugin","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}