Registry / devops / unplugin-utils

unplugin-utils

JSON →
library0.3.1jsnpmunverified

unplugin-utils is a lean, platform-agnostic library providing essential utility functions specifically designed for developing 'unplugins'—plugins that aim for universal compatibility across various JavaScript bundlers like Vite, Webpack, Rollup, and esbuild. It offers common helpers such as `createFilter` for efficient file path inclusion/exclusion matching and `normalizePath` for consistent path handling across different operating systems. The current stable version is 0.3.1, and the project is actively maintained with frequent minor updates and occasional breaking changes. Its key differentiators include a focus on platform agnosticism (supporting browser and Node.js environments), a smaller bundle footprint compared to alternatives due to a carefully selected subset of functionalities, and a commitment to 100% test coverage. The library is heavily inspired by and incorporates concepts from `@rollup/pluginutils` but is tailored for broader 'unplugin' ecosystem needs.

npm install unplugin-utils
INSTALL
IMPORT
SIG · UNPLUGIN-UTILS
U
unplugin-utils
devopsjavascriptv0.3.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

createFilter
import { createFilter } from 'unplugin-utils'
const { createFilter } = require('unplugin-utils')
The package is ESM-only since v0.3.0. Use ES module import syntax.
normalizePath
import { normalizePath } from 'unplugin-utils'
const { normalizePath } = require('unplugin-utils')
Since v0.3.0, CommonJS `require` is not supported. Ensure your project is configured for ESM.
UnpluginInstance
import type { UnpluginInstance } from 'unplugin-utils'
import { UnpluginInstance } from 'unplugin-utils'
Import types using `import type` to avoid runtime overhead and ensure correct TypeScript compilation.

This quickstart demonstrates how to create a basic unplugin using `createFilter` and `normalizePath` to conditionally transform code based on file paths.

import { createFilter, normalizePath } from 'unplugin-utils'; import type { UnpluginBuildContext, UnpluginOptions } from 'unplugin'; interface MyPluginOptions { include?: string | RegExp | (string | RegExp)[]; exclude?: string | RegExp | (string | RegExp)[]; enable?: boolean; } export default function myUnplugin(options: MyPluginOptions = {}): UnpluginOptions { const filter = createFilter(options.include, options.exclude); return { name: 'my-custom-unplugin', buildStart(this: UnpluginBuildContext) { if (!options.enable) { this.warn('My plugin is disabled.'); return; } console.log('My Unplugin build started!'); }, transform(code: string, id: string) { const normalizedId = normalizePath(id); if (!filter(normalizedId)) { return null; // Skip transformation if id does not match filter } // Example transformation: prepend a comment const transformedCode = `// Transformed by my-custom-unplugin\n${code}`; console.log(`Transformed file: ${normalizedId}`); return transformedCode; }, buildEnd() { console.log('My Unplugin build ended!'); } }; }
Debug
Known issues
breakingStarting from v0.3.0, unplugin-utils dropped its CommonJS (CJS) build. Attempting to use `require()` will result in import errors.
fix
Migrate your project to use ES module import syntax (`import ... from 'unplugin-utils'`). Ensure your build configuration supports ESM.
affects: >=0.3.0
breakingVersion 0.3.0 officially dropped support for Node.js 18 and earlier. The package now requires Node.js version 20.19.0 or higher.
fix
Upgrade your Node.js environment to version 20.19.0 or newer to ensure compatibility.
affects: >=0.3.0
breakingVersion 0.2.4 introduced a breaking change related to escaping backslashes (`\`). This might affect how paths are resolved or processed, especially on Windows.
fix
Review any custom path handling logic in your unplugins. It is recommended to consistently use `normalizePath` from `unplugin-utils` to ensure cross-platform compatibility.
affects: >=0.2.4
breakingA function was renamed in version 0.2.0. If you are upgrading from 0.1.x, existing calls to the old function name will break.
fix
Consult the changelog for v0.2.0 on GitHub to identify the specific renamed function and update your code accordingly.
affects: >=0.2.0 <0.3.0
Errors
Common errors & fixes
TypeError: require is not a function
Attempting to use CommonJS `require()` syntax to import `unplugin-utils` in a project that is configured for ES modules, or after upgrading to `unplugin-utils` v0.3.0+ which is ESM-only.
fix
Update your import statements from `const { someUtil } = require('unplugin-utils')` to `import { someUtil } from 'unplugin-utils'`.
Error: The CJS build has been dropped since Node.js 18 is EOL. Please use ESM.
This explicit error message indicates you are trying to use an older CommonJS import method with `unplugin-utils` v0.3.0 or later.
fix
Refactor your imports to use ES module syntax: `import { createFilter } from 'unplugin-utils'` and ensure your project's `package.json` specifies `"type": "module"` or uses `.mjs` files.
Error: unsupported Node.js version. unplugin-utils requires Node.js >=20.19.0.
Running `unplugin-utils` v0.3.0 or later on an unsupported Node.js version (e.g., Node.js 18 or earlier).
fix
Upgrade your Node.js runtime to version 20.19.0 or a later compatible version.
TypeError: Cannot read properties of undefined (reading 'myOldFunctionName')
This often occurs if a function you were using in a previous version of `unplugin-utils` (pre-v0.2.0) was renamed or removed in a breaking change.
fix
Refer to the v0.2.0 changelog to identify the renamed function. Update your code to use the new function name.
Upgrade
Version history
0.3.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
unplugin-utils — npm install unplugin-utils · libregistry