babel-plugin-relative-path-import

2.0.1 verified Sat Apr 25 auth: no javascript maintenance

babel-plugin-relative-path-import (stable v2.0.1, Babel 7+) enables root-based import paths (e.g., '@actions/UserAction') as an alternative to deeply nested relative paths. Supports multiple custom prefix/suffix mappings. Differentiates from Webpack resolve aliases by working at the Babel transform level, allowing compatibility with tools that don't resolve Webpack aliases. Primarily used with Node.js/React projects. Last updated 2019, see more recent alternatives like babel-plugin-root-import.

Common errors

error Error: Plugin/preset files are not allowed to export objects, only functions. ↓

cause Attempting to import or use the plugin incorrectly in a JavaScript file that is not a Babel config.

fix

Use the plugin only as a string in Babel configuration, not as an imported module.

error Module not found: Can't resolve '@/components/Button' ↓

cause Path prefix not mapped correctly or plugin not applied during Webpack build.

fix

Verify rootPathSuffix is correct and that Babel plugin runs before Webpack resolves modules.

Warnings

breaking Version 2.0.0+ is only compatible with Babel 7; Babel 6 users must use v1.x. ↓

fix If on Babel 6, install version 1.0.5 or lower.

deprecated The default rootPathPrefix changed from '@' in v1 to still '@' but the paths option now expects an array of objects instead of a single object. ↓

fix Update config to use array format as shown in README.

gotcha This plugin does not affect runtime resolution; paths are only transformed at build time. If using Node.js runtime without Babel, imports will fail. ↓

fix Ensure you use Babel for both build and runtime, or use a runtime resolver like module-alias.

breaking The plugin no longer supports the old single-object configuration schema from v1. ↓

fix Migrate to the new array-based paths configuration.

Install

npm install babel-plugin-relative-path-import

yarn add babel-plugin-relative-path-import

pnpm add babel-plugin-relative-path-import

Imports

default

wrong

import plugin from 'babel-plugin-relative-path-import';

correct

module.exports = { plugins: [['babel-plugin-relative-path-import', { paths: [{ rootPathPrefix: '@', rootPathSuffix: 'src' }] }]] }

Used as a Babel plugin in .babelrc or babel.config.js, not imported directly in source code.

Quickstart

Configures Babel to resolve '@'-prefixed imports relative to a 'src' directory.

// .babelrc
{
  "plugins": [
    [
      "babel-plugin-relative-path-import",
      {
        "paths": [
          {
            "rootPathPrefix": "@",
            "rootPathSuffix": "src"
          }
        ]
      }
    ]
  ]
}

// src/app.js
import UserAction from '@actions/UserAction'; // resolves to src/actions/UserAction.js