Registry / serialization / babel-plugin-node-cjs-interop

babel-plugin-node-cjs-interop

library0.1.9jsnpmunverified

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.

serialization

npm install babel-plugin-node-cjs-interop

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-NODE-

babel-plugin-node-cjs-interop

serializationjavascriptv0.1.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

babel-plugin-node-cjs-interop

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

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

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

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.

Debug

Known issues

gotchaThe 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.

affects: >=0.0.0

gotchaNamed 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.

affects: >=0.0.0

gotchaImporting 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.

affects: >=0.0.0

gotchaThe 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.

affects: >=0.0.0

gotchaFalse 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.

affects: >=0.0.0

Errors

Common errors & fixes

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

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']

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

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.

Upgrade

Version history

0.1.9latest on npm

Audit

Dependencies

@babel/corerequiredPeer dependency required for Babel plugin functionality

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/qnighy/node-cjs-interop ↗

packagehttps://www.npmjs.com/package/babel-plugin-node-cjs-interop ↗