babel-root-import

4.1.8 verified Sat Apr 25 auth: no javascript renamed

Babel plugin to enable root-relative imports (e.g., import Foo from '@/foo') in JavaScript/TypeScript projects. Version 4.1.8 is the legacy package, renamed to babel-plugin-root-import (latest v6.6.0). This plugin transforms root-relative paths to relative paths at build time. Key differentiator: simple configuration (rootPathSuffix) and support for dynamic imports. Often confused with webpack aliases but works at Babel level. Low release cadence: last update 2019. Consider using babel-plugin-root-import instead, which is the maintained successor.

Common errors

error Error: Cannot find module '@some/module' ↓

cause Root import path not transformed correctly due to missing or misconfigured plugin options.

fix

Ensure babel-root-import is installed and configured with rootPathSuffix and rootPathPrefix in .babelrc or babel.config.js.

error Module not found: Can't resolve '@/foo' in '/path/to/project' ↓

cause Webpack or other bundler cannot resolve the @ alias; the plugin only transforms to relative paths at Babel level, but the bundler may need its own alias.

fix

Add a corresponding alias in webpack config (resolve.alias) or use a different root import approach.

error SyntaxError: Unexpected token / ↓

cause Using root import syntax (e.g., import from '@/foo') without Babel processing (e.g., running node directly).

fix

Ensure your code is transpiled with Babel before running, or use node with a require hook like @babel/register.

Warnings

deprecated Package is renamed to babel-plugin-root-import. babel-root-import will no longer receive updates. ↓

fix Use babel-plugin-root-import instead. Requires uninstalling this package and installing the new one.

breaking Root path prefix changed default from '~' in early versions to '@/' in version 5+. ↓

fix Update prefix in code and configuration to '@/' or set a custom prefix.

gotcha Options object must be wrapped in an array in the plugins list. Common mistake: passing object directly. ↓

fix Use array syntax: ["babel-root-import", { rootPathSuffix: "src" }]

gotcha The plugin does not work without a rootPathSuffix; default is './' which may not resolve as expected. ↓

fix Set rootPathSuffix to your source directory (e.g., 'src') or adjust it appropriately.

Install

npm install babel-root-import

yarn add babel-root-import

pnpm add babel-root-import

Imports

default (plugin)
wrong
```
module.exports = { plugins: ['babel-root-import'] }
```
correct
```
module.exports = { plugins: [['babel-root-import', { rootPathSuffix: 'src' }]] }
```
Options must be passed as an array with the plugin name and options object. Missing options leads to default behavior (root = './'), which may not work as expected.
default (plugin) with .babelrc
wrong
```
{ "plugins": ["babel-root-import"] }
```
correct
```
{ "plugins": [["babel-root-import", { "rootPathSuffix": "src" }]] }
```
In .babelrc JSON, the plugin and options must be an array in an array. Omitting options is common but may cause root resolution to fail.
Import syntax usage
wrong
```
import Foo from '/foo' or import Foo from '~/foo'
```
correct
```
import Foo from '@/foo'
```
Default root prefix is '@/'. Other prefixes like '~' are not supported without custom configuration (rootPathPrefix).

Quickstart

Shows installation, .babelrc configuration with custom root suffix and prefix, and an example import resolving to a src-relative path.

// Install: npm install --save-dev babel-root-import
// Configure in .babelrc:
{
  "plugins": [
    ["babel-root-import", {
      "rootPathSuffix": "src",
      "rootPathPrefix": "@/"
    }]
  ]
}

// Usage in src/app.js:
import User from '@/models/user';  // resolves to ./src/models/user
console.log(User);