babel-plugin-root-import: A JavaScript repository from raffy2010

Babel plugin to add the opportunity to use import and require with root based paths.

Example

// Without this plugin...
import SomeExample from '../../../some/example.js';
const OtherExample = require('../../../other/example.js');

// With babel-plugin-root-import you can write...
import SomeExample from '~/some/example.js';
const OtherExample = require('~/other/example.js');

Install

Install with your package manager of choice.

npm install babel-plugin-root-import --save-dev
# or
yarn add babel-plugin-root-import --dev

Use

Add it to your plugins array in your babel config, e.g. a .babelrc file.

{
  "plugins": [
    ["babel-plugin-root-import"]
  ]
}

For recent react-native versions, add it as a plugin in babel.config.js:

module.exports = (api) => {
  api.cache(true);

  return {
    plugins: [
      'babel-plugin-root-import',
    ],
  };
}

For the rest of this readme, it's implied that you'll configure the plugin as above when using react-native.

Config

You can configure this plugin by changing the string plugin name to a two-item array. Note that this array is nested inside the plugins array. Here's an example with the default config.

  "plugins": [
    [
      "babel-plugin-root-import",
      {
        "rootPathSuffix": "./",
        "rootPathPrefix": "~"
      }
    ]
  ],

Custom rootPathSuffix

By default, the import will be relative to the working directory of the process running babel. Typically this means you'll have import paths like ~/src/foo.js. You can change the prefix of "./" to e.g. "src" or "src/js" with this config option.

{
  "plugins": [
    ["babel-plugin-root-import", {
      "rootPathSuffix": "src/js"
    }]
  ]
}

The paths "src/js" and "./src/js" behave the same.

Custom rootPathPrefix

If you don't like the ~ syntax you can use your own symbol (for example an # symbol or \). Using @ is not recommended, as recent versions of NPM allow @ in package names. ~ is the default since it's very unlikely to conflict with anything (and wouldn't be expanded to HOME anyway).

This must be 1 or 2 characters. Any additional characters are ignored.

// 
// Waiting this change: https://github.com/entwicklerstube/babel-plugin-root-import/pull/97
{ 
  "plugins": [
    ["babel-plugin-root-import", {
      "rootPathPrefix": "#"
    }]
  ]
}

// Now you can use the plugin like either of these
import foo from '#my-file';
import foo from '#/my-file';

If you set it to e.g. "#/" then it'll require the slash in the import path.

Multiple custom prefixes and suffixes

You can supply an array of the above. The plugin will try each prefix/suffix pair in the order they are defined.

{
  "plugins": [
    ["babel-plugin-root-import", {
      "paths": [{
        // `~` is the default so you can remove this if you want
        "rootPathPrefix": "~",
        "rootPathSuffix": "src/js"
      }, {
        "rootPathPrefix": "@",
        "rootPathSuffix": "other-src/js"
      }, {
        // since we suport relative paths you can also go into a parent directory
        "rootPathPrefix": "#",
        "rootPathSuffix": "../../src/in/parent"
      }]
    }]
  ]
}

// Now you can use the plugin like:
import foo from '~/foo';
const bar = require('@/bar');

Don't let ESLint be confused

If you use eslint-plugin-import to validate imports it may be necessary to instruct ESLint to parse root imports. You can use eslint-import-resolver-babel-plugin-root-import

    "import/resolver": {
      "babel-plugin-root-import": {}
    }

Don't let Flow be confused

If you use Facebook's Flow for type-checking it is necessary to instruct it on how to map your chosen prefix to the root directory. Add the following to your .flowconfig file, replacing {rootPathPrefix} with your chosen prefix and {rootPathSuffix} with your chosen suffix.

[options]
module.name_mapper='^{rootPathPrefix}/\(.*\)$' -> '<PROJECT_ROOT>/{rootPathSuffix}/\1'

Don't let VSCode be confused

For features like go-to-definition, VSCode needs to be able to resolve require/import paths to files on disk. This only works with one rootPathSuffix, but you may define multiple rootPathPrefix entries.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "{rootPathPrefix}/*": ["src/*"]
    }
  }
}

For example, with ~/x/y.js -> ./src/x/y.js:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["src/*"]
    }
  }
}

FYI

Webpack delivers a similar feature, if you just want to prevent end-less import strings you can also define aliases in the resolve module, at the moment it doesn't support custom/different symbols and multiple/custom suffixes. READ MORE

Want to revert back to relative paths?

Sometimes tooling might not be up to scratch, meaning you lose features such as navigation in your IDE. In such cases you might want to revert back to using relative paths again. If you have a significant amount of files, it might be worth looking into tooling to help you with the conversion.

Change Log

6.1.0 - 2018-06-23

Supports babel 7

5.0.0 - 2017-02-10

More consistent name: babel-plugin-root-import #63
Renamed everything
Publish with new name on npm

4.1.5 - 2016-11-17

Compile new version and release again

4.1.4 - 2016-11-15

Improve support for relative paths (e.g. referencing parent folders via ../) (thanks to @Hizoul)

4.1.3 - 2016-09-14

Support paths (thanks to @sivael)

4.1.0 - 2016-08-20

Use relative paths instead of absolute ones (thanks to @nescalante)

4.0.0 - 2016-06-29

Almost everything changed, thanks to @sheepsteak, @gingur, @olalonde

3.2.2 - 2016-02-20

Fix custom suffix in path, missing / in generated paths

3.2.0 - 2016-02-19

Support Windows-Filesystem
Add possibility to configure a custom rootPath-Symbol (instead of ~ you can use whatever you like)

3.1.0 - 2015-12-01

Add possibility config the custom root path

3.0.1 - 2015-11-30

Updated plugin to new babel6 API
Splitted tests and functions into two scopes with single tests
Removed the "extra-root" param for the .babelrc since this is no yet supported in babel6

2.0.1 - 2015-11-15

Breaking Change to Babel 5

Updated to Babel 6
Added integration tests

1.0.1 - 2015-08-07

Added / updated tests
Implemented ESlint

raffy2010/babel-plugin-root-import