rollup-plugin-commonjs-alternate

0.8.0 verified Mon Apr 27 auth: no javascript maintenance

A Rollup plugin that converts CommonJS modules to ES modules, designed as an alternative to @rollup/plugin-commonjs. Version 0.8.0 is the latest. It improves on the official plugin by supporting conditional requires (only including the correct branch), detecting require calls in ESM files (e.g., for React Hot Loader), and not stubbing dynamic requires (essential for HMR). It is useful for front-end libraries with best-practice module patterns, but may not work with libraries that reassign module.exports. Named exports require explicit configuration. Suitable for Rollup bundling in development and production.

Common errors

error Error: Cannot find module 'react' ↓

cause The plugin does not resolve modules; it only converts CJS to ESM. You need a resolve plugin.

fix

Add @rollup/plugin-node-resolve before the commonjs plugin in the plugins array.

error TypeError: Cannot read properties of undefined (reading 'isModule') ↓

cause Node module resolution is incomplete; the plugin may not handle certain module formats.

fix

Update to the latest version and add necessary resolve and external plugins.

Warnings

gotcha Named exports must be explicitly configured; auto-detection does not work. ↓

fix Use namedExports option to specify exported names per module.

gotcha Dynamic requires are not converted to static imports; they remain as require calls that may break in the bundle. ↓

fix Avoid dynamic requires; if needed, handle them manually or use a different plugin.

gotcha The plugin assumes all CommonJS modules are in strict mode; non-strict modules may cause unexpected behavior. ↓

fix Ensure all CJS modules have 'use strict' or are compliant with strict mode.

breaking Version 0.7.0 changed default extensions from ['.js', '.json'] to ['.js'] ↓

fix If you need .json support, set extensions to ['.js', '.json'] explicitly.

Install

npm install rollup-plugin-commonjs-alternate

yarn add rollup-plugin-commonjs-alternate

pnpm add rollup-plugin-commonjs-alternate

Imports

commonjs

wrong

import { commonjs } from 'rollup-plugin-commonjs-alternate'

correct

import commonjs from 'rollup-plugin-commonjs-alternate'

Default export only; named export is incorrect.

commonjs (require)

wrong

const { commonjs } = require('rollup-plugin-commonjs-alternate')

correct

const commonjs = require('rollup-plugin-commonjs-alternate')

CJS require gives the default function directly; destructuring is wrong.

Plugin with options

wrong

commonjs({ namedExports: { 'react': { Component: 'Component' } } })

correct

commonjs({ namedExports: { 'react': ['Component'] } })

namedExports is an object mapping module ID to array of exported names, not a map of exports.

Quickstart

Demonstrates configuring the plugin with namedExports, extensions, and define options in a Rollup config.

// rollup.config.js
import commonjs from 'rollup-plugin-commonjs-alternate';
import resolve from '@rollup/plugin-node-resolve';
import json from '@rollup/plugin-json';

export default {
  input: 'src/index.js',
  output: { file: 'dist/bundle.js', format: 'iife' },
  plugins: [
    resolve(),
    commonjs({
      namedExports: {
        'node_modules/react/index.js': ['Component', 'createElement']
      },
      extensions: ['.js', '.jsx'],
      define: {
        'process.env.NODE_ENV': JSON.stringify('production')
      }
    }),
    json()
  ]
};