{"id":19106,"library":"babel-plugin-module-name-mapper","title":"babel-plugin-module-name-mapper","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/mgcrea/babel-plugin-module-name-mapper","tags":["javascript"],"install":[{"cmd":"npm install babel-plugin-module-name-mapper","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-module-name-mapper","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-module-name-mapper","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Must provide an options object with moduleNameMapper map, even if empty.","wrong":"plugins: ['module-name-mapper']","symbol":"plugin","correct":"plugins: [['module-name-mapper', { moduleNameMapper: { '^src/(.*)': '<pkgDir>/src/$1' } }]]"},{"note":"Use ^ and $ boundaries to avoid unintended matches; patterns without boundaries may cause errors with substrings (e.g., 'relay' matches 'react-relay').","wrong":"moduleNameMapper: { 'src/(.*)': '<pkgDir>/src/$1' }","symbol":"moduleNameMapper","correct":"moduleNameMapper: { '^src/(.*)': '<pkgDir>/src/$1' }"},{"note":"Plugin is default-exported as a function; named exports do not exist.","wrong":"const { moduleNameMapper } = require('babel-plugin-module-name-mapper');","symbol":"require()","correct":"const plugin = require('babel-plugin-module-name-mapper');"}],"quickstart":{"code":"// Install\nyarn add --dev babel-plugin-module-name-mapper\n\n// .babelrc or babel.config.js\nmodule.exports = {\n  presets: [['@babel/preset-env']],\n  plugins: [\n    [\n      'module-name-mapper',\n      {\n        moduleNameMapper: {\n          '^src/(.*)': '<pkgDir>/src/$1',\n          '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub',\n          '^[./a-zA-Z0-9$_-]+\\.png$': '<rootDir>/RelativeImageStub.js',\n        }\n      }\n    ]\n  ]\n};\n\n// Usage: instead of import ... from '../../../helpers/foo.js'\nimport fooHelper from 'src/helpers/example.js';","lang":"javascript","description":"Shows installation, configuration with multiple mappings using <pkgDir> and <rootDir> tokens, and usage example replacing relative path hell."},"warnings":[{"fix":"Always use ^ and $ boundaries in your moduleNameMapper patterns.","message":"Patterns without ^ and $ boundaries can cause hard-to-spot errors, replacing substrings (e.g., 'relay' matches 'graphql-relay').","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add to plugins array only.","message":"The plugin is not a Babel preset; it must be listed in the plugins array, not presets.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use <pkgDir> for monorepo package root; <rootDir> remains available.","message":"Version 1.0.0 introduced <pkgDir> token; earlier versions only supported <rootDir>.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Evaluate migration to babel-plugin-module-resolver if newer features are needed.","message":"The plugin has not been updated since 2020; consider using babel-plugin-module-resolver as an alternative with broader support.","severity":"deprecated","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure pattern uses ^src/(.*) and replacement uses correct token like <pkgDir>/src/$1.","cause":"moduleNameMapper pattern not matching because missing ^ and $ boundaries or wrong token.","error":"Error: Cannot find module 'src/helpers/example.js'"},{"fix":"Use plugins: [['module-name-mapper', { moduleNameMapper: {} }]] even if no mappings.","cause":"Plugin listed without options but options are required.","error":"Error: Plugin is not a function"},{"fix":"Pass an object with moduleNameMapper key: plugins: [['module-name-mapper', { moduleNameMapper: { ... } }]].","cause":"Plugin options not provided or have wrong shape.","error":"TypeError: Cannot read properties of undefined (reading 'moduleNameMapper')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}