rollup-plugin-module-replacement

1.2.1 verified Mon Apr 27 auth: no javascript maintenance

A Rollup plugin (v1.2.1) that replaces module paths during bundling, similar to Webpack's NormalModuleReplacementPlugin. Supports string or regex pattern matching with replacement strings or functions for dynamic rewrites. Ideal for environment-specific builds (e.g., swapping mock vs production modules). Unlike rollup-plugin-alias, it does not resolve modules internally, allowing custom resolvers (e.g., rollup-plugin-node-resolve) to be passed in. Released under MIT, with irregular updates (last in 2020).

Common errors

error Error: Could not resolve './some-module' from src/index.js ↓

cause Module replacement did not map to an existing file, or no customResolver handled the replaced path.

fix

Ensure replacement produces a valid path, or pass a customResolver as second argument to the plugin.

error TypeError: replacement is not a function ↓

cause Incorrect import: using named import instead of default import.

fix

Use: import replacement from 'rollup-plugin-module-replacement'

error The plugin 'rollup-plugin-module-replacement' does not support the 'transform' hook. ↓

cause Plugin only uses resolveId hook; trying to use it for code transformation will fail.

fix

Use this plugin only for module path replacement, not for content transformation.

Warnings

gotcha Plugin does not resolve replaced paths internally; if no customResolver is passed, the replacement string is used as-is in Rollup's resolve hook, which may lead to unresolved modules. ↓

fix Pass a resolver plugin (e.g., rollup-plugin-node-resolve) as the second argument or ensure replacement results in an absolute path.

gotcha The order of entries matters: first matching rule is applied. Subsequent rules are not processed for the same import. ↓

fix Order entries from most specific to least specific to avoid unintended matches.

deprecated rollup-plugin-node-resolve is now @rollup/plugin-node-resolve. ↓

fix Replace imports from 'rollup-plugin-node-resolve' to '@rollup/plugin-node-resolve'.

gotcha Replacement function must return a string; returning undefined or null will cause Rollup to fail resolving module. ↓

fix Always return a string from the replacement function. For unmatched patterns, return the original importee.

Install

npm install rollup-plugin-module-replacement

yarn add rollup-plugin-module-replacement

pnpm add rollup-plugin-module-replacement

Imports

default

wrong

const replacement = require('rollup-plugin-module-replacement')

correct

import replacement from 'rollup-plugin-module-replacement'

Plugin is ESM-only; CJS require will fail in Rollup ES configs.

replacement

wrong

import { replacement } from 'rollup-plugin-module-replacement'

correct

import replacement from 'rollup-plugin-module-replacement'

No named export; must use default import.

replacement as named

wrong

import { replaceModules } from 'rollup-plugin-module-replacement'

correct

import replacer from 'rollup-plugin-module-replacement'

Only default export; no alias export exists.

Quickstart

Demonstrates regex-based module replacement with a custom resolver using rollup-plugin-node-resolve.

// rollup.config.js
import replacement from 'rollup-plugin-module-replacement';
import resolve from 'rollup-plugin-node-resolve';

const customResolver = resolve({ extensions: ['.mjs', '.js', '.jsx'] });

export default {
  input: 'src/index.js',
  output: { file: 'dist/bundle.js', format: 'cjs' },
  plugins: [
    replacement(
      {
        entries: [
          {
            find: /src\/(.*)/,
            replacement: (importee) => {
              const env = process.env.BUILD_ENV || 'prod';
              return importee.replace('src', `src-${env}`);
            }
          }
        ]
      },
      customResolver
    ),
    resolve()
  ]
};