babel-plugin-root-import

5.4.0 verified Sat Apr 25 auth: no javascript

A Babel plugin that allows you to use root-based import paths (e.g., `~/foo`) instead of long relative paths (`../../../foo`). The current stable version is v5.4.0, with an active maintenance status (the latest release v6.6.0 came later but the package appears to be maintained). It supports custom prefix and suffix, multiple path mappings, and works with both `import` and `require`. Compared to Webpack's alias feature, this plugin operates at the Babel level, making it useful for tools like `babel-node` and testing environments where Webpack resolve is not available. It requires Babel 7 (or 6 depending on version).

Common errors

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

cause The plugin is not configured correctly or the root path suffix does not lead to the correct directory.

fix

Check your .babelrc: ensure 'babel-plugin-root-import' is in the plugins array and that 'rootPathSuffix' points to the correct subdirectory containing your source files. Also verify that Babel is actually running on the file (e.g., through webpack loader or babel-node).

error Error: Plugin 0 specified in "..." provided an invalid property of "rootPrefix" ↓

cause Typo in option name: 'rootPrefix' instead of 'rootPathPrefix'.

fix

Change 'rootPrefix' to 'rootPathPrefix' in your .babelrc options.

error Error: Requires Babel "^7.0.0-0", but was loaded with "6.26.3" ↓

cause You have installed a version of babel-plugin-root-import that requires Babel 7 but your project uses Babel 6.

fix

Install an older version of the plugin: npm install babel-plugin-root-import@5 --save-dev (v5.x supports Babel 6) or upgrade your project to Babel 7.

Warnings

breaking Version 5.0.0 changed the plugin name from 'babel-root-import' to 'babel-plugin-root-import'. ↓

fix Update your .babelrc to use 'babel-plugin-root-import' instead of 'babel-root-import'.

gotcha The plugin transforms imports during Babel transpilation, not at runtime. If you use a module bundler like Webpack, you may have duplicate substitutions or conflicts with Webpack's own alias resolution. ↓

fix Consider using Webpack's resolve.alias instead of this plugin if you are already using Webpack. If you must use both, ensure the plugin's rootPathPrefix does not clash with Webpack aliases.

gotcha When using ESLint with eslint-plugin-import, root imports will be flagged as unresolved unless you configure eslint-import-resolver-babel-root-import. ↓

fix Add 'import/resolver' configuration in your ESLint config: {"babel-plugin-root-import": {}}

deprecated The 'rootPathSuffix' option defaults to the project root, but many users expect it to be the current working directory. This is not a bug, but a common misunderstanding. ↓

fix Explicitly set 'rootPathSuffix' to the directory relative to which you want root imports to resolve (e.g., 'src').

Install

npm install babel-7-plugin-root-import

yarn add babel-7-plugin-root-import

pnpm add babel-7-plugin-root-import

Imports

plugin
wrong
```
import plugin from 'babel-plugin-root-import'; // not a runtime import
```
correct
```
// .babelrc: "plugins": ["babel-plugin-root-import"]
```
This is a Babel plugin, not a runtime library. It is configured in .babelrc or babel.config.js, not imported in application code.

options: rootPathPrefix

wrong

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

correct

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

The correct option key is 'rootPathPrefix', not 'prefix' or 'rootPrefix'. This is a common typo.

options: rootPathSuffix

wrong

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

correct

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

The correct option key is 'rootPathSuffix', not 'suffix'. If not set, the root defaults to the project directory.

Quickstart

Installs the plugin, configures .babelrc with a root path suffix pointing to 'src', and demonstrates using the ~ prefix to import a module relative to the project root.

npm install --save-dev babel-plugin-root-import

echo '{
  "plugins": [
    ["babel-plugin-root-import", {
      "rootPathSuffix": "src"
    }]
  ]
}' > .babelrc

# Create an example file
mkdir -p src/utils
cat > src/index.js << 'EOF'
import { helper } from '~/utils/helper';
console.log(helper);
EOF
cat > src/utils/helper.js << 'EOF'
export const helper = 'Hello from root import!';
EOF

# Run with babel-node
npx babel-node src/index.js
# Output: Hello from root import!