Unplugin Utilities

0.3.1 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: require is not a function
```
cause 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.
```
cause 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.
```
cause 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')
```
cause 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.

Warnings

breaking Starting 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.
breaking Version 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.
breaking Version 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.
breaking A 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.

Install

npm install unplugin-utils npm
yarn add unplugin-utils yarn
pnpm add unplugin-utils pnpm

Imports

createFilter

wrong:

const { createFilter } = require('unplugin-utils')

correct:

import { createFilter } from 'unplugin-utils'

The package is ESM-only since v0.3.0. Use ES module import syntax.

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

Quickstart

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!');
    }
  };
}

view raw JSON →