Registry / devops / babel-7-plugin-root-import

babel-7-plugin-root-import

library5.4.0jsnpmunverified

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

devops

npm install babel-7-plugin-root-import

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-7-PLUGIN-ROO

babel-7-plugin-root-import

devopsjavascriptv5.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

plugin

✓ // .babelrc: "plugins": ["babel-plugin-root-import"]

✗ import plugin from 'babel-plugin-root-import'; // not a runtime 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

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

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

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

options: rootPathSuffix

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

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

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

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!

Debug

Known issues

breakingVersion 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'.

affects: <5.0.0

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

affects: >=1.0.0

gotchaWhen 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": {}}

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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: Plugin 0 specified in "..." provided an invalid property of "rootPrefix"

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

fix

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

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

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.

Upgrade

Version history

5.4.0latest on npm

Audit

Dependencies

@babel/corerequiredRequired as a peer dependency for plugin resolution.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/entwicklerstube/babel-plugin-root-import ↗

packagehttps://www.npmjs.com/package/babel-7-plugin-root-import ↗