Registry / babel-plugin-root-import

babel-plugin-root-import

library6.6.0jsnpmunverified

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.

npm install babel-plugin-root-import

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-ROOT-

babel-plugin-root-import

javascriptv6.6.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.

default plugin

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

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

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

require (CommonJS)

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

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

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

dynamic import

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

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

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

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 => { // ... });

Debug

Known issues

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

affects: all

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

fix

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

affects: all

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

affects: <6.2.0

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

affects: all

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

affects: all

Errors

Common errors & fixes

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

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: Plugin babel-plugin-root-import not found

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

The 'rootPathPrefix' option must be a string

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

fix

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

Template literals are not supported in dynamic imports with this version

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

Upgrade

Version history

6.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

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

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