Registry / devops / babel-plugin-module-name-mapper

babel-plugin-module-name-mapper

library1.2.0jsnpmunverified

Babel plugin that adds Jest-like moduleNameMapper support to Babel, enabling import path rewriting with special tokens <pkgDir> and <rootDir>. <pkgDir> resolves to the directory of the closest package.json, making it ideal for monorepos. Current stable version is 1.2.0. Release cadence is low; maintained. Key differentiator: supports <pkgDir> for monorepo-friendly path resolution, which is lacking in Jest and Webpack. Alternative to babel-plugin-module-resolver with different token semantics.

devops web-framework

npm install babel-plugin-module-name-mapper

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-MODUL

babel-plugin-module-name-mapper

devopsjavascriptv1.2.0

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.

plugin

✓ plugins: [['module-name-mapper', { moduleNameMapper: { '^src/(.*)': '<pkgDir>/src/$1' } }]]

✗ plugins: ['module-name-mapper']

Must provide an options object with moduleNameMapper map, even if empty.

moduleNameMapper

✓ moduleNameMapper: { '^src/(.*)': '<pkgDir>/src/$1' }

✗ moduleNameMapper: { 'src/(.*)': '<pkgDir>/src/$1' }

Use ^ and $ boundaries to avoid unintended matches; patterns without boundaries may cause errors with substrings (e.g., 'relay' matches 'react-relay').

require()

✓ const plugin = require('babel-plugin-module-name-mapper');

✗ const { moduleNameMapper } = require('babel-plugin-module-name-mapper');

Plugin is default-exported as a function; named exports do not exist.

Shows installation, configuration with multiple mappings using <pkgDir> and <rootDir> tokens, and usage example replacing relative path hell.

// Install yarn add --dev babel-plugin-module-name-mapper // .babelrc or babel.config.js module.exports = { presets: [['@babel/preset-env']], plugins: [ [ 'module-name-mapper', { moduleNameMapper: { '^src/(.*)': '<pkgDir>/src/$1', '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub', '^[./a-zA-Z0-9$_-]+\.png$': '<rootDir>/RelativeImageStub.js', } } ] ] }; // Usage: instead of import ... from '../../../helpers/foo.js' import fooHelper from 'src/helpers/example.js';

Debug

Known issues

gotchaPatterns without ^ and $ boundaries can cause hard-to-spot errors, replacing substrings (e.g., 'relay' matches 'graphql-relay').

fix

Always use ^ and $ boundaries in your moduleNameMapper patterns.

affects: >=1.0.0

gotchaThe plugin is not a Babel preset; it must be listed in the plugins array, not presets.

fix

Add to plugins array only.

affects: >=1.0.0

breakingVersion 1.0.0 introduced <pkgDir> token; earlier versions only supported <rootDir>.

fix

Use <pkgDir> for monorepo package root; <rootDir> remains available.

affects: >=1.0.0

deprecatedThe plugin has not been updated since 2020; consider using babel-plugin-module-resolver as an alternative with broader support.

fix

Evaluate migration to babel-plugin-module-resolver if newer features are needed.

affects: >=1.2.0

Errors

Common errors & fixes

Error: Cannot find module 'src/helpers/example.js'

moduleNameMapper pattern not matching because missing ^ and $ boundaries or wrong token.

fix

Ensure pattern uses ^src/(.*) and replacement uses correct token like <pkgDir>/src/$1.

Error: Plugin is not a function

Plugin listed without options but options are required.

fix

Use plugins: [['module-name-mapper', { moduleNameMapper: {} }]] even if no mappings.

TypeError: Cannot read properties of undefined (reading 'moduleNameMapper')

Plugin options not provided or have wrong shape.

fix

Pass an object with moduleNameMapper key: plugins: [['module-name-mapper', { moduleNameMapper: { ... } }]].

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mgcrea/babel-plugin-module-name-mapper ↗

packagehttps://www.npmjs.com/package/babel-plugin-module-name-mapper ↗