Babel Plugin Node CJS Interop

0.1.9 verified Sat Apr 25 auth: no javascript

A Babel plugin (v0.1.9) that fixes the default import interoperability issue when importing simulated ESM (CommonJS modules with __esModule flag) from native ES modules in Node.js. This plugin automatically wraps export values to ensure default imports work correctly. Compared to alternatives, it automates the wrapping process. Maintained by qnighy, with releases as needed. Also available as swc-plugin-node-cjs-interop for SWC users.

Common errors

error TypeError: greet is not a function at ./b.mjs:3:1 ↓

cause Default import from a simulated ESM (CommonJS with __esModule) to native ESM fails because the module exports a default property but Node.js ESM expects direct function export.

fix

Add the problematic package to babel-plugin-node-cjs-interop's packages list. Example: packages: ['styled-components']

error SyntaxError: The requested module '...' does not provide an export named 'default' ↓

cause Node.js ESM cannot find the default export from a CommonJS module that has __esModule flag.

fix

Use babel-plugin-node-cjs-interop with the package name listed in the configuration.

Warnings

gotcha The plugin does NOT detect re-exports (export ... from). Modules using re-exports may still cause default import failures. ↓

fix Manually wrap re-exported modules or avoid re-exports from simulated ESM packages.

gotcha Named imports from simulated ESM modules may not reflect live bindings correctly when imported from native ESM. The plugin restores live update semantics but can cause behavioral differences in rare cases. ↓

fix Be aware that importing mutable exports from simulated ESM may behave differently. Test thoroughly.

gotcha Importing a non-existent named export from a simulated ESM module with this plugin will return undefined instead of throwing an error like native ESM does. ↓

fix Ensure all named exports exist in the imported package. Use TypeScript or check package exports.

gotcha The plugin may negatively affect tree-shaking because wrapper functions obscure unused import analysis. ↓

fix Limit the packages list to only those experiencing issues. Consider using node-cjs-interop-finder to detect problematic packages.

gotcha False positives can occur if a package uses the __esModule flag for purposes other than indicating Babel-transpiled ES modules. ↓

fix Manually verify affected packages and test imports.

Install

npm install babel-plugin-node-cjs-interop

yarn add babel-plugin-node-cjs-interop

pnpm add babel-plugin-node-cjs-interop

Imports

babel-plugin-node-cjs-interop

wrong

// CommonJS require can't be used directly in .babelrc.js

correct

// In .babelrc.js or babel.config.js
plugins: [
  ['babel-plugin-node-cjs-interop', { packages: ['styled-components'] }]
]

Configure as a Babel plugin, not imported directly. For CommonJS configs, use module.exports.

Quickstart

Shows how to install and configure the Babel plugin to fix default import interoperability with native ES modules.

// Install: npm install -D babel-plugin-node-cjs-interop

// .babelrc.js
module.exports = {
  presets: [
    ['@babel/preset-env', { modules: false }]
  ],
  plugins: [
    ['babel-plugin-node-cjs-interop', {
      packages: ['styled-components', 'some-package']
    }]
  ]
};

// Then build with Babel. The plugin will add compatibility wrappers
// to ensure default imports work from native ESM.