rollup-plugin-modify

3.0.0 verified Mon Apr 27 auth: no javascript

Rollup plugin for find-and-replace transformations on output bundles. Version 3.0.0 is current and stable, with no major release cadence. Supports both string/regex find with string/function replace, and a terse object syntax for multiple replacements. Uses magic-string under the hood for source map preservation. Unlike @rollup/plugin-replace, this plugin operates on the entire output file content rather than on AST nodes, making it suitable for regex-based codemods.

Common errors

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

cause rollup-plugin-modify v3+ is ESM-only, so require() fails.

fix

Use dynamic import: const modify = (await import('rollup-plugin-modify')).default;

error TypeError: modify is not a function ↓

cause Using named import { modify } instead of default import.

fix

Use import modify from 'rollup-plugin-modify' (no braces).

error The 'find' argument must be of type string or an instance of RegExp ↓

cause Passed non-string/non-RegExp as find (e.g., array or number).

fix

Ensure find is either a string or RegExp. For multiple patterns, use the terse object syntax or multiple plugins.

Warnings

breaking rollup-plugin-modify v3 is ESM-only and requires Node.js >= 12. Modules must be loaded via import. ↓

fix Update Node.js to >=12 and use ESM imports. For CJS projects, use dynamic import() or stick to v2.

breaking The options format changed from v1/v2. The legacy 'options' object with separate 'find' and 'replace' is still supported, but the terse key-value object syntax is now the primary use. ↓

fix If you were using a single options object with 'find' and 'replace' keys, that still works. No migration needed unless you used undocumented API.

gotcha When using the terse object syntax, all keys are treated as strings (find patterns). To use a RegExp, you must use the explicit { find, replace } syntax. ↓

fix Use the explicit syntax for RegExp: modify({ find: /pattern/, replace: 'replacement' })

gotcha The replace function receives the entire match array from String.prototype.replace, not just the first argument. Ensure your function signature matches the expected (match, ...groups) pattern. ↓

fix Use (match, ...args) => { ... } and extract groups as needed.

Install

npm install rollup-plugin-modify

yarn add rollup-plugin-modify

pnpm add rollup-plugin-modify

Imports

default (modify)

wrong

const modify = require('rollup-plugin-modify')

correct

import modify from 'rollup-plugin-modify'

Package is ESM-only since v3. CommonJS require() will fail.

Named export (none)

wrong

import { modify } from 'rollup-plugin-modify'

correct

import modify from 'rollup-plugin-modify'

There is no named export; only a default export.

TypeScript types
wrong
```
import modify = require('rollup-plugin-modify')
```
correct
```
import modify from 'rollup-plugin-modify'
```
TypeScript should use ESM import syntax. Types are included in the package.

Quickstart

Replaces process.env.* variables with actual environment variables in the output bundle, using a dynamic replace function.

// rollup.config.js
import modify from 'rollup-plugin-modify'

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'es'
  },
  plugins: [
    modify({
      find: /process\.env\.([\w_]+)/g,
      replace: (match, key) => process.env[key] ?? ''
    })
  ]
}