babel-plugin-module-resolver

A Babel plugin to add a new resolver for your modules when compiling your code using Babel. This plugin allows you to add new "root" directories that contain your modules. It also allows you to setup a custom alias for directories, specific files, or even other npm modules.

Description

This plugin can simplify the require/import paths in your project. For example, instead of using complex relative paths like ../../../../utils/my-utils, you can write utils/my-utils. It will allow you to work faster since you won't need to calculate how many levels of directory you have to go up before accessing the file.

// Use this:
import MyUtilFn from 'utils/MyUtilFn';
// Instead of that:
import MyUtilFn from '../../../../utils/MyUtilFn';

// And it also work with require calls
// Use this:
const MyUtilFn = require('utils/MyUtilFn');
// Instead of that:
const MyUtilFn = require('../../../../utils/MyUtilFn');

Usage

If you're coming from babel-plugin-module-alias, please read this section: Updating from babel-plugin-module-alias.

Install the plugin

$ npm install --save-dev babel-plugin-module-resolver

Specify the plugin in your .babelrc with the custom root or alias. Here's an example:

{
  "plugins": [
    ["module-resolver", {
      "root": ["./src"],
      "alias": {
        "test": "./test",
        "underscore": "lodash"
      }
    }]
  ]
}

Options

• root: Array of root directories. Specify the paths or a glob path (eg. ./src/**/components)
• alias: Map of alias. You can also alias node_modules dependencies, not just local files.
• extensions: Array of extensions used in the resolver. Override the default extensions (['.js', '.jsx', '.es', '.es6']).
• cwd: By default, the working directory is the one used for the resolver, but you can override it for your project.
  • The custom value babelrc will make the plugin look for the closest babelrc configuration based on the file to parse.
  • The custom value packagejson will make the plugin look for the closest package.json based on the file to parse.

Regular expression alias

It is possible to specify an alias using a regular expression. To do that, either start an alias with '^' or end it with '$':

{
  "plugins": [
    ["module-resolver", {
      "alias": {
        "^@namespace/foo-(.+)": "packages/\\1"
      }
    }]
  ]
}

Using the config from this example '@namespace/foo-bar' will become 'packages/bar'.

You can reference the n-th matched group with '\\n' ('\\0' refers to the whole matched path).

To use the backslash character (\) just escape it like so: '\\\\' (double escape is needed because of JSON already using \ for escaping).

Updating from babel-plugin-module-alias

babel-plugin-module-resolver is a new version of the old babel-plugin-module-alias. Therefore, you also need to make a few modifications to your plugin configuration to make it work with this new plugin.

Updating is very easy. For example, if you had this configuration:

// This configuration is outdated, this is just an example
{
  "plugins": [
    ["module-alias", [
      { "src": "./src/utils", "expose": "utils" },
      { "src": "./src/components", "expose": "components" },
      { "src": "./src/actions", "expose": "actions" },
      { "src": "npm:lodash", "expose": "underscore" }
    ]]
  ]
}

You only have to update the plugin options to be like this:

{
  "plugins": [
      ["module-resolver", {
        "root": ["./src"],
        "alias": {
          "underscore": "lodash"
        }
      }]
    ]
}

ESLint plugin

If you're using ESLint, you should use eslint-plugin-import, and eslint-import-resolver-babel-module to remove falsy unresolved modules.

Usage with Flow

To allow Flow to find your modules, add configuration options to .flowconfig.

For example, a React component is located at src/components/Component.js

// Before
import '../../src/components/Component';

// After - Flow cannot find this now
import 'components/Component';

Instruct Flow where to resolve modules from:

# .flowconfig

[options]
module.system.node.resolve_dirname=node_modules
module.system.node.resolve_dirname=src

Be sure to add any sub-directories if you refer to files further down the directory tree:

// Located at src/store/actions
import 'actions/User'

module.system.node.resolve_dirname=src/store

Or you may use name_mapper option for manual listing (tested with Flow 0.45):

# .flowconfig

[options]
; Be careful with escaping characters in regexp
- module.name_mapper='^app\/(.*)$' -> '<PROJECT_ROOT>/app/\1' # does not work
+ module.name_mapper='^app\/\(.*\)$' -> '<PROJECT_ROOT>/app/\1' # work as expected

; Other modules
module.name_mapper='^i18n\/\(.*\)$' -> '<PROJECT_ROOT>/i18n/\1'
module.name_mapper='^schema\/\(.*\)$' -> '<PROJECT_ROOT>/schema/\1'
module.name_mapper='^mongoose-elasticsearch-xp\(.*\)$' -> '<PROJECT_ROOT>/lib/mongoose-elasticsearch-xp\1'

More configuration options are located in the Flow documentation

Editors autocompletion

• Atom: Uses atom-autocomplete-modules and enable the babel-plugin-module-resolver option.
• IntelliJ/WebStorm: You can add custom resources root directories, make sure it matches what you have in this plugin.

License

MIT, see LICENSE.md for details.