babel-plugin-root-import

6.6.0 verified Sat Apr 25 auth: no javascript

Babel plugin that allows import and require with root-based paths, replacing relative path traversal (e.g., `../../../`) with a configurable prefix like `~/` or `@/`. Version 6.6.0 is the current stable release, actively maintained. Key differentiators: simple setup, multiple custom root path rules, support for dynamic imports and template literals. Still widely used but newer alternatives like `babel-plugin-module-resolver` offer more features (e.g., aliasing, TypeScript). Release cadence is irregular; last major update in 2020.

Common errors

error Module not found: Can't resolve '~/something' ↓

cause Plugin not configured or not applied; or rootPathSuffix points to wrong directory.

fix

Ensure plugin is in .babelrc plugins array and rootPathSuffix is correct relative to CWD.

error Error: Plugin babel-plugin-root-import not found ↓

cause Package not installed or missing from node_modules.

fix

Run 'npm install --save-dev babel-plugin-root-import' or 'yarn add --dev babel-plugin-root-import'.

error The 'rootPathPrefix' option must be a string ↓

cause Misconfigured plugin options; used array or object instead of tuple [name, options].

fix

Use nested array format: ['babel-plugin-root-import', { rootPathPrefix: '~/' }].

error Template literals are not supported in dynamic imports with this version ↓

cause Using babel-plugin-root-import version < 6.6.0 which did not support template literals in import() expressions.

fix

Upgrade to v6.6.0 or later, or avoid template literals (use simple string literals).

Warnings

gotcha Default root path suffix is './' so '~/foo' resolves to CWD/foo, not CWD/src/foo. Most users expect ~/ to point to src/. ↓

fix Set rootPathSuffix to './src' (or your source directory) in plugin options.

deprecated The '@' prefix is not recommended as NPM allows '@' in package names and can cause conflicts. ↓

fix Use '~/' or another prefix that does not start with '@'.

breaking In v6.2.0, the 2-character restriction on rootPathPrefix was removed. Prefixes with fewer than 2 characters now work but may cause unexpected matches. ↓

fix Upgrade to >=6.2.0 or ensure prefix is at least 2 characters long (excluding slash).

gotcha The plugin transforms source files only; it does not affect runtime resolution. Webpack or other bundlers may still need separate alias configuration. ↓

fix If using a bundler, configure corresponding aliases (e.g., in webpack resolve.alias) to match the root prefix.

gotcha When using with TypeScript, the plugin only rewrites import paths in JS output. TypeScript compiler (tsc) still needs its own path mapping (paths in tsconfig.json) to resolve the same aliases for type checking. ↓

fix Add equivalent path mappings in tsconfig.json compilerOptions.paths.

Install

npm install babel-plugin-root-import

yarn add babel-plugin-root-import

pnpm add babel-plugin-root-import

Imports

default plugin

wrong

plugins: ['babel-plugin-root-import', { rootPathPrefix: '~/' }] // wrong: config must be nested array

correct

// in babel.config.js
plugins: ['babel-plugin-root-import']

Configuration is passed as the second element of a tuple: [pluginName, options].

require (CommonJS)

wrong

const path = require('babel-plugin-root-import').resolve('~/my-module'); // no such API

correct

const path = require('~/my-module');

The plugin transforms source code at build time; no runtime API.

dynamic import

wrong

import(`~/my-${name}`).then(mod => ...); // template literals supported since v6.6.0, but older versions may fail

correct

import('~/my-module').then(mod => ...);

Template literals in dynamic imports are supported from v6.6.0 onward.

Quickstart

Shows how to configure the plugin with custom prefix and suffix, and use it with static require/import and dynamic import with template literals.

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

// file: src/app.js
import MyComponent from '~/components/MyComponent';
// resolves to ./src/components/MyComponent relative to process cwd

// file: src/other.js
const utils = require('~/utils/helper');
// resolves to ./src/utils/helper.js

// dynamic import with template literal (v6.6.0+)
const moduleName = 'dashboard';
import(`~/pages/${moduleName}`).then(module => {
  // ...
});