rollup-plugin-regexp

5.0.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin for dynamic find-and-replace operations in bundled output using regular expressions or string matching. Version 5.0.1 is the latest stable release, published with a moderate cadence. Unlike static string replacement plugins, it supports RegExp patterns and replacement functions, enabling codemods and dynamic content injection. Ships TypeScript types and uses magic-string for accurate sourcemap preservation. A key differentiator is the shorthand syntax allowing key-value pairs for multiple replacements.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module [...] not supported. ↓

cause Attempting to require() an ESM-only package in a CommonJS module.

fix

Use dynamic import: const regexpPlugin = await import('rollup-plugin-regexp'); or use import syntax. Alternatively, downgrade to v4.

error TypeError: regexpPlugin is not a function ↓

cause Wrong import style – likely using default import when package was required as an object.

fix

Ensure import is default: import regexpPlugin from 'rollup-plugin-regexp' (no curly braces).

error Cannot read properties of undefined (reading 'replace') ↓

cause Passing an undefined or non-string value as 'find' or 'replace' option.

fix

Check that 'find' is a string or RegExp, and 'replace' is a string or function.

error The 'regexpPlugin' option 'find' must be a string or RegExp. ↓

cause Passing an object or boolean to 'find'.

fix

Ensure 'find' is a string or RegExp. If using shorthand syntax, keys must be strings.

Warnings

breaking Version 5.0.0 dropped support for CommonJS (require). If using Node.js <12 or bundling for CommonJS, pin to version 4.x. ↓

fix Use import syntax or downgrade to 'rollup-plugin-regexp@4'

breaking Prior to v5, package was named 'rollup-plugin-modify'. The package was renamed; old imports break. ↓

fix Update imports from 'rollup-plugin-modify' to 'rollup-plugin-regexp'

gotcha Replacement function receives the match array from String.prototype.replace(). If using a global regex, the function is called multiple times but the 'offset' parameter may be off if replacements change string length. ↓

fix Ensure replacement function correctly handles all parameters: match, p1, p2, ..., offset, string.

deprecated The 'include' and 'exclude' options (from @rollup/pluginutils) were deprecated in v5 in favor of Rollup's built-in filter plugins like 'rollup-plugin-filter'. ↓

fix Use external filter plugins or omit; the plugin only transforms matched files.

gotcha When using multiple instances with overlapping patterns, execution order matters and may cause unintended replacements if one instance modifies the same code as another. ↓

fix Order plugins carefully or consolidate replacements into a single instance.

Install

npm install rollup-plugin-regexp

yarn add rollup-plugin-regexp

pnpm add rollup-plugin-regexp

Imports

default (rollup-plugin-regexp)
wrong
```
const regexpPlugin = require('rollup-plugin-regexp')
```
correct
```
import regexpPlugin from 'rollup-plugin-regexp'
```
Package is ESM-only; no CommonJS export. Use dynamic import if needed in CJS context.
RegexpPlugin (named export)
wrong
```
import RegexpPlugin from 'rollup-plugin-regexp'
```
correct
```
import { RegexpPlugin } from 'rollup-plugin-regexp'
```
Named export is available but default export is more commonly used. Both work identically.
TypeScript types
```
import type { RollupRegexpOptions } from 'rollup-plugin-regexp'
```
Types are exported from the package, so no separate @types/ package is needed.

Quickstart

Shows default import, a regex replacement using a function, and the shorthand multiple replacement syntax.

import regexpPlugin from 'rollup-plugin-regexp';
import { defineConfig } from 'rollup';

export default defineConfig({
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    regexpPlugin({
      find: /process\.env\.MY_VAR/g,
      replace: () => JSON.stringify(process.env.MY_VAR ?? 'default')
    }),
    // Multiple replacements shorthand:
    regexpPlugin({
      '__BUILD_TIME__': new Date().toISOString(),
      '__VERSION__': '1.0.0'
    })
  ]
});