{"id":12314,"library":"unplugin-utils","title":"Unplugin Utilities","description":"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.","status":"active","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/sxzz/unplugin-utils","tags":["javascript","typescript"],"install":[{"cmd":"npm install unplugin-utils","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only since v0.3.0. Use ES module import syntax.","wrong":"const { createFilter } = require('unplugin-utils')","symbol":"createFilter","correct":"import { createFilter } from 'unplugin-utils'"},{"note":"Since v0.3.0, CommonJS `require` is not supported. Ensure your project is configured for ESM.","wrong":"const { normalizePath } = require('unplugin-utils')","symbol":"normalizePath","correct":"import { normalizePath } from 'unplugin-utils'"},{"note":"Import types using `import type` to avoid runtime overhead and ensure correct TypeScript compilation.","wrong":"import { UnpluginInstance } from 'unplugin-utils'","symbol":"UnpluginInstance","correct":"import type { UnpluginInstance } from 'unplugin-utils'"}],"quickstart":{"code":"import { createFilter, normalizePath } from 'unplugin-utils';\nimport type { UnpluginBuildContext, UnpluginOptions } from 'unplugin';\n\ninterface MyPluginOptions {\n  include?: string | RegExp | (string | RegExp)[];\n  exclude?: string | RegExp | (string | RegExp)[];\n  enable?: boolean;\n}\n\nexport default function myUnplugin(options: MyPluginOptions = {}): UnpluginOptions {\n  const filter = createFilter(options.include, options.exclude);\n\n  return {\n    name: 'my-custom-unplugin',\n    buildStart(this: UnpluginBuildContext) {\n      if (!options.enable) {\n        this.warn('My plugin is disabled.');\n        return;\n      }\n      console.log('My Unplugin build started!');\n    },\n    transform(code: string, id: string) {\n      const normalizedId = normalizePath(id);\n      if (!filter(normalizedId)) {\n        return null; // Skip transformation if id does not match filter\n      }\n\n      // Example transformation: prepend a comment\n      const transformedCode = `// Transformed by my-custom-unplugin\\n${code}`;\n      console.log(`Transformed file: ${normalizedId}`);\n      return transformedCode;\n    },\n    buildEnd() {\n      console.log('My Unplugin build ended!');\n    }\n  };\n}","lang":"typescript","description":"This quickstart demonstrates how to create a basic unplugin using `createFilter` and `normalizePath` to conditionally transform code based on file paths."},"warnings":[{"fix":"Migrate your project to use ES module import syntax (`import ... from 'unplugin-utils'`). Ensure your build configuration supports ESM.","message":"Starting from v0.3.0, unplugin-utils dropped its CommonJS (CJS) build. Attempting to use `require()` will result in import errors.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Upgrade your Node.js environment to version 20.19.0 or newer to ensure compatibility.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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.","message":"Version 0.2.4 introduced a breaking change related to escaping backslashes (`\\`). This might affect how paths are resolved or processed, especially on Windows.","severity":"breaking","affected_versions":">=0.2.4"},{"fix":"Consult the changelog for v0.2.0 on GitHub to identify the specific renamed function and update your code accordingly.","message":"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.","severity":"breaking","affected_versions":">=0.2.0 <0.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statements from `const { someUtil } = require('unplugin-utils')` to `import { someUtil } from 'unplugin-utils'`.","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.","error":"TypeError: require is not a function"},{"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.","cause":"This explicit error message indicates you are trying to use an older CommonJS import method with `unplugin-utils` v0.3.0 or later.","error":"Error: The CJS build has been dropped since Node.js 18 is EOL. Please use ESM."},{"fix":"Upgrade your Node.js runtime to version 20.19.0 or a later compatible version.","cause":"Running `unplugin-utils` v0.3.0 or later on an unsupported Node.js version (e.g., Node.js 18 or earlier).","error":"Error: unsupported Node.js version. unplugin-utils requires Node.js >=20.19.0."},{"fix":"Refer to the v0.2.0 changelog to identify the renamed function. Update your code to use the new function name.","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.","error":"TypeError: Cannot read properties of undefined (reading 'myOldFunctionName')"}],"ecosystem":"npm"}