Registry / babel-plugin-replace-import-extension

babel-plugin-replace-import-extension

library1.1.5jsnpmunverified

A Babel plugin that replaces file extensions in import statements and dynamic imports during transpilation. Current stable version is 1.1.5, with irregular release cadence. It solves the problem of co-existing ESModule and CommonJS builds by rewriting relative imports (starting with ./ or ../) so that, for example, .js becomes .mjs or .cjs. Unlike other extension replacement approaches, it handles dynamic imports by injecting a __transformExtension helper and avoids changes to bare specifiers (node_modules). It works with @babel/transform-modules-commonjs and is configured via an extMapping option.

npm install babel-plugin-replace-import-extension

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-REPLA

babel-plugin-replace-import-extension

javascriptv1.1.5

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.

default (plugin)

✓ import babelPluginReplaceImportExtension from 'babel-plugin-replace-import-extension'

✗ const babelPluginReplaceImportExtension = require('babel-plugin-replace-import-extension')

ESM default import works. CJS require also works via .default property.

babel-plugin-replace-import-extension

✓ module.exports = { plugins: [['replace-import-extension', { extMapping: { '.js': '.mjs' } }]] }

✗ module.exports = { plugins: ['babel-plugin-replace-import-extension', { extMapping: { '.js': '.mjs' } }] }

Plugin name in config is 'replace-import-extension' (not the full npm package name). Options are passed as second array element.

with preset/env

✓ module.exports = { presets: [['@babel/env']], plugins: [['replace-import-extension', { extMapping: { '.js': '.cjs' } }]] }

✗ module.exports = { plugins: [['replace-import-extension', { extMapping: { '.js': '.cjs' } }], ['@babel/env']] }

Order matters: transform-modules-commonjs or @babel/env should be listed after the replace-import-extension plugin.

Shows basic usage: install plugin, configure extMapping in Babel config, and expected transformation of static and dynamic imports.

// Install: npm install --save-dev babel-plugin-replace-import-extension // Example .babelrc { "plugins": [ ["replace-import-extension", { "extMapping": { ".js": ".mjs" } }] ] } // Input import { foo } from './module.js'; export { bar } from './utils.js'; const promise = import('./data' + '.js'); // Output import { foo } from './module.mjs'; export { bar } from './utils.mjs'; // Dynamic import helpers are inserted at runtime const promise = import(__transformExtension('./data' + '.js')); // Build command (example): npx babel src --out-dir dist --out-file-extension .mjs

Debug

Known issues

gotchaOnly relative imports (starting with './' or '../') are converted. Bare specifiers like 'lodash' are never modified.

fix

Ensure all local file imports use relative paths if you expect extension replacement.

affects: >=1.0.0

gotchaDynamic import extension replacement only works when the import argument is a string literal or concatenation of string literals. Fully dynamic expressions like import(someVar) are not transformed.

fix

Update to v1.1.4+ which handles constant dynamic imports. For fully dynamic, consider runtime helper.

affects: <1.1.4

breakingIn v1.1.3, a fix was applied to avoid recursively loading babelrc or babel config, which could change behavior if your setup relied on recursive resolution.

fix

Update to v1.1.3+ to avoid potential infinite loops.

affects: <1.1.3

gotchaThe plugin injects a __transformExtension helper function for dynamic imports. This may conflict if you already have a global function or variable with that name.

fix

Avoid using __transformExtension in your codebase, or check if plugin version allows renaming (not available by default).

affects: >=1.0.0

deprecatedNo deprecation warnings yet, but the package has had infrequent releases (last release 2023). Verify compatibility with newer Babel versions.

fix

Test with your Babel version; if issues, consider alternatives like babel-plugin-transform-import-extension or manual string replacement.

affects: latest

Errors

Common errors & fixes

Cannot find module 'babel-plugin-replace-import-extension'

Missing npm package or incorrect plugin name in config.

fix

Run 'npm install --save-dev babel-plugin-replace-import-extension' and use plugin name 'replace-import-extension' (without the 'babel-plugin-' prefix) in .babelrc.

TypeError: extMapping is not defined

Options object is missing the extMapping key or is malformed.

fix

Ensure config is an array with options object: ['replace-import-extension', { extMapping: { '.js': '.mjs' } }].

Cannot read properties of undefined (reading 'call')

Plugin incompatible with Babel version (e.g., Babel 6 vs 7).

fix

Update to babel-plugin-replace-import-extension v1.1.5+ and ensure Babel 7 is installed.

Dynamic import not transformed: 'import(' + expr + ')'

Dynamic import argument is not a constant string expression.

fix

Only string literals or concatenation of literals are supported. For variable expressions, consider a runtime helper.

Upgrade

Version history

1.1.5latest on npm

Audit

Dependencies

@babel/corerequiredPeer dependency for Babel plugin API

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/silane/babel-plugin-replace-import-extension ↗

packagehttps://www.npmjs.com/package/babel-plugin-replace-import-extension ↗