{"id":19153,"library":"babel-plugin-replace-import-extension","title":"babel-plugin-replace-import-extension","description":"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.","status":"active","version":"1.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/silane/babel-plugin-replace-import-extension","tags":["javascript","babel","plugin","replace","convert","transform","rewrite","import","extension"],"install":[{"cmd":"npm install babel-plugin-replace-import-extension","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-replace-import-extension","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-replace-import-extension","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Babel plugin API","package":"@babel/core","optional":false}],"imports":[{"note":"ESM default import works. CJS require also works via .default property.","wrong":"const babelPluginReplaceImportExtension = require('babel-plugin-replace-import-extension')","symbol":"default (plugin)","correct":"import babelPluginReplaceImportExtension from 'babel-plugin-replace-import-extension'"},{"note":"Plugin name in config is 'replace-import-extension' (not the full npm package name). Options are passed as second array element.","wrong":"module.exports = { plugins: ['babel-plugin-replace-import-extension', { extMapping: { '.js': '.mjs' } }] }","symbol":"babel-plugin-replace-import-extension","correct":"module.exports = { plugins: [['replace-import-extension', { extMapping: { '.js': '.mjs' } }]] }"},{"note":"Order matters: transform-modules-commonjs or @babel/env should be listed after the replace-import-extension plugin.","wrong":"module.exports = { plugins: [['replace-import-extension', { extMapping: { '.js': '.cjs' } }], ['@babel/env']] }","symbol":"with preset/env","correct":"module.exports = { presets: [['@babel/env']], plugins: [['replace-import-extension', { extMapping: { '.js': '.cjs' } }]] }"}],"quickstart":{"code":"// Install: npm install --save-dev babel-plugin-replace-import-extension\n// Example .babelrc\n{\n  \"plugins\": [\n    [\"replace-import-extension\", {\n      \"extMapping\": {\n        \".js\": \".mjs\"\n      }\n    }]\n  ]\n}\n\n// Input\nimport { foo } from './module.js';\nexport { bar } from './utils.js';\nconst promise = import('./data' + '.js');\n\n// Output\nimport { foo } from './module.mjs';\nexport { bar } from './utils.mjs';\n// Dynamic import helpers are inserted at runtime\nconst promise = import(__transformExtension('./data' + '.js'));\n\n// Build command (example): npx babel src --out-dir dist --out-file-extension .mjs\n","lang":"javascript","description":"Shows basic usage: install plugin, configure extMapping in Babel config, and expected transformation of static and dynamic imports."},"warnings":[{"fix":"Ensure all local file imports use relative paths if you expect extension replacement.","message":"Only relative imports (starting with './' or '../') are converted. Bare specifiers like 'lodash' are never modified.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update to v1.1.4+ which handles constant dynamic imports. For fully dynamic, consider runtime helper.","message":"Dynamic 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.","severity":"gotcha","affected_versions":"<1.1.4"},{"fix":"Update to v1.1.3+ to avoid potential infinite loops.","message":"In 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.","severity":"breaking","affected_versions":"<1.1.3"},{"fix":"Avoid using __transformExtension in your codebase, or check if plugin version allows renaming (not available by default).","message":"The plugin injects a __transformExtension helper function for dynamic imports. This may conflict if you already have a global function or variable with that name.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Test with your Babel version; if issues, consider alternatives like babel-plugin-transform-import-extension or manual string replacement.","message":"No deprecation warnings yet, but the package has had infrequent releases (last release 2023). Verify compatibility with newer Babel versions.","severity":"deprecated","affected_versions":"latest"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","cause":"Missing npm package or incorrect plugin name in config.","error":"Cannot find module 'babel-plugin-replace-import-extension'"},{"fix":"Ensure config is an array with options object: ['replace-import-extension', { extMapping: { '.js': '.mjs' } }].","cause":"Options object is missing the extMapping key or is malformed.","error":"TypeError: extMapping is not defined"},{"fix":"Update to babel-plugin-replace-import-extension v1.1.5+ and ensure Babel 7 is installed.","cause":"Plugin incompatible with Babel version (e.g., Babel 6 vs 7).","error":"Cannot read properties of undefined (reading 'call')"},{"fix":"Only string literals or concatenation of literals are supported. For variable expressions, consider a runtime helper.","cause":"Dynamic import argument is not a constant string expression.","error":"Dynamic import not transformed: 'import(' + expr + ')'","affected_versions":">=1.0.0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}