Skip to content

Latest commit

 

History

History
364 lines (290 loc) · 9.37 KB

DOCS.md

File metadata and controls

364 lines (290 loc) · 9.37 KB
Raw

Getting Started

Install the plugin

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

or

yarn add --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

A string or an array of root directories. Specify the paths or a glob path (eg. ./src/**/components) node_modules is an implicit root as it is a default directory to resolve modules

alias

A map of alias. You can also alias node_modules dependencies, not just local files.

Regular expressions

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).

Passing a substitute function

If you need even more power over the aliased path, you can pass a function in the alias configuration:

module.exports = {
  plugins: [
    ["module-resolver", {
      alias: {
        "foo": ([, name]) => `bar${name}`,
        "^@namespace/foo-(.+)": ([, name]) => `packages/${name}`
      }
    }]
  ]
}

Using the config from this example:

  • 'foo' will become 'bar' (name is empty)
  • 'foo/baz' will become 'bar/baz' (name includes the slash in this case)
  • '@namespace/foo-bar' will become 'packages/bar'

The only argument is the result of calling RegExp.prototype.exec on the matched path. It's an array with the matched string and all matched groups.

Because the function is only called when there is a match, the argument can never be null.

extensions

An array of extensions used in the resolver.

{
  "plugins": [
    [
      "module-resolver",
      {
        "extensions": [".js", ".jsx", ".es", ".es6", ".mjs"]
      }
    ]
  ]
}

stripExtensions

An array of extensions that will be stripped from file paths. Defaults to the extensions option value.

{
  "plugins": [
    [
      "module-resolver",
      {
        "stripExtensions": [".js", ".jsx", ".es", ".es6", ".mjs"]
      }
    ]
  ]
}

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.
{
  "plugins": [
    ["module-resolver", {
      "cwd": "babelrc"
    }]
  ]
}
  • The custom value packagejson will make the plugin look for the closest package.json based on the file to parse.
{
  "plugins": [
    ["module-resolver", {
      "cwd": "packagejson"
    }]
  ]
}

transformFunctions

Array of functions and methods that will have their first argument transformed. By default those methods are: require, require.resolve, System.import, jest.genMockFromModule, jest.mock, jest.unmock, jest.doMock, jest.dontMock.

{
  "plugins": [
    ["module-resolver", {
      "transformFunctions": [
          "require",
          "require.resolve",
          "System.import",
          "jest.genMockFromModule",
          "jest.mock",
          "jest.unmock",
          "jest.doMock",
          "jest.dontMock"
      ]
    }]
  ]
}

resolvePath

A function that is called to resolve each path in the project. By default module-resolver is using an internal function - the same one that's exported from the plugin itself (see For plugin authors for more info).

module.exports = {
  plugins: [
    ["module-resolver", {
      extensions: [".js"],
      resolvePath(sourcePath, currentFile, opts) {
        /**
         * The `opts` argument is the options object that is passed through the Babel config.
         * opts = {
         *   extensions: [".js"],
         *   resolvePath: ...,
         * }
         */
        return "resolvedPath";
      }
    }]
  ]
}

If you want to leave some paths as-is, then you can return undefined or any other falsy value from the function.

loglevel

One of the NPM log level options to configure console logging during build. Default is "warn". Passing "silent" will disable all warnings for path resolution failures.

module.exports = {
  plugins: [
    ["module-resolver", {
      alias: {
        "dependency-string": "module-that-does-not-exist" // warning will not log
      },
      loglevel: 'silent'
    }]
  ]
}

Usage with create-react-app

create-react-app by default don't use .babelrc, so in webpack.config.dev.js, add plugins property within js loader like below. Note that plugins recieve an array.

// Process JS with Babel.
{
  test: /\.(js|jsx|mjs)$/,
  include: paths.appSrc,
  loader: require.resolve('babel-loader'),
  options: {
    plugins: [
        ["module-resolver", {
        "root": ["./src/App"],
        "alias": {
          "test": "./test",
        }
      }]
    ],
    cacheDirectory: true
  }
}

Usage with React Native

To let the packager resolve the right module for each platform, you have to add the .ios.jsand .android.js extensions :

{
  "plugins": [
    [
      "module-resolver",
      {
        "root": ["./src"],
        "extensions": [".ios.js", ".android.js", ".js", ".json"]
      }
    ]
  ]
}

Usage with Proxyquire

If you use the mocking library proxyquire, or otherwise need to define path strings which aren't direct arguments to transformFunctions, you have a problem: the plug-in won't convert them.

Because proxyquire expects paths not just as direct arguments, but also as object keys, simply adding proxyquire to transformFunctions isn't enough:

const { functionToTest } = proxyquire('~/modifiedPathToTestedModule', { // this path will be converted
    '~/modifiedPathToDependency': { mockVersionOfDependency } // this path won't be converted
});

The solution in this case is to use or create a function like Lodash's/Underscore's _.identity, which simply returns its argument. Next, add it to transformFunctions, and then use it to convert the problematic path string:

"transformFunctions": [
    "proxyquire",
    "resolvePath"
]
const resolvePath = x => x;
const { functionToTest } = proxyquire('~/modifiedPathToTestedModule', { // this path will be converted
    [resolvePath('~/modifiedPathToDependency')]: { mockVersionOfDependency } // this path will be converted
});

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

For plugin authors

Aside from the main export, which is the plugin itself as needed by Babel, there is a function used internally that is exposed:

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

// `opts` are the options as passed to the Babel config (should have keys like "root", "alias", etc.)
const realPath = resolvePath(sourcePath, currentFile, opts);

For each path in the file you can use resolvePath to get the same path that module-resolver will output.

currentFile can be either a relative path (will be resolved with respect to the CWD, not opts.cwd), or an absolute path.