babel-plugin-module-resolver

5.0.3 verified Sat Apr 25 auth: no javascript

A Babel plugin that allows custom module resolution by defining root directories and aliases, eliminating deep relative imports like '../../../../utils'. It simplifies import/require paths for cleaner code. Current stable version is 5.0.3 (July 2024). Release cadence is irregular, with major version bumps occasionally (v4 in 2020, v5 in 2023). Key differentiators: supports both import and require, works with Babel 7+, and integrates with ESLint via eslint-import-resolver-babel-module for linting. Alternative: TypeScript's paths in tsconfig.json but this plugin works for plain JavaScript/Babel projects.

Common errors

error Module not found: Can't resolve 'utils/MyUtilFn' in '/path/to/file' ↓

cause The alias 'utils' points to a directory that doesn't exist or is not a valid path.

fix

Ensure the alias value is correct and the directory exists. Use absolute paths or './src' relative to project root.

error Error: Cannot find module 'babel-plugin-module-resolver' ↓

cause Plugin is not installed as a devDependency.

fix

Run npm install --save-dev babel-plugin-module-resolver or yarn add --dev babel-plugin-module-resolver.

error Error: The 'cwd' option is deprecated and will be removed in future versions. ↓

cause Using the 'cwd' option in plugin configuration.

fix

Replace 'cwd' with 'root' and use absolute paths or './src' relative to project root.

Warnings

breaking V4 changed the way aliases are resolved: paths without leading ./ or ../ are now treated as module names, not relative paths. This may break aliases to npm packages. ↓

fix Prefix alias paths with ./ or ../ to enforce relative resolution, or update alias values to match the new semantics.

gotcha Plugins can't resolve paths during ESLint linting unless you also configure eslint-import-resolver-babel-module. ↓

fix Add eslint-import-resolver-babel-module to your ESLint config and set the same root/alias options.

gotcha The plugin does not affect runtime resolution; it only rewrites during Babel transpilation. Ensure your runtime environment has the same module resolution or bundler config. ↓

fix Configure Webpack resolve.alias or TypeScript paths separately for runtime.

deprecated The 'cwd' option (deprecated in v5) will be removed. Use 'root' with absolute paths instead. ↓

fix Replace 'cwd' with 'root' and use absolute paths or './src' relative to project root.

Install

npm install babel-plugin-module-resolver

yarn add babel-plugin-module-resolver

pnpm add babel-plugin-module-resolver

Imports

default
wrong
```
const plugin = require('babel-plugin-module-resolver')
```
correct
```
import plugin from 'babel-plugin-module-resolver'
```
In .babelrc.js, use require.resolve('babel-plugin-module-resolver') for the plugin. Common mistake: using require directly without resolve.

resolvePath

wrong

const { resolvePath } = require('babel-plugin-module-resolver').default

correct

import { resolvePath } from 'babel-plugin-module-resolver'

resolvePath is a named export for plugin authors. Available since v3. ESM-only in v5+.

types
```
import type { PluginOptions } from 'babel-plugin-module-resolver'
```
Type imports for TypeScript users. PluginOptions type can be used in .babelrc.ts.

Quickstart

Configures the plugin in .babelrc with root and alias, then shows a simplified import path.

// .babelrc
{
  "plugins": [
    ["module-resolver", {
      "root": ["./src"],
      "alias": {
        "utils": "./src/utils",
        "@components": "./src/components"
      }
    }]
  ]
}

// Before
import MyComponent from '../../../../components/MyComponent';

// After
import MyComponent from '@components/MyComponent';