babel-project-relative-import

2.0.1 verified Sat Apr 25 auth: no javascript maintenance

Babel plugin (v2.0.1) that transforms project-relative import paths (e.g., '~') into file-relative paths during build. Unlike alternatives like babel-root-import that convert to absolute paths, this plugin produces relative output for portability across systems. Tested with babel-cli, webpack, and task runners. Last release appears stable, but the project is in maintenance mode with infrequent updates.

Common errors

error Cannot find module 'babel-project-relative-import' ↓

cause Plugin not installed or typo in package name

fix

Run npm install babel-project-relative-import --save-dev and check .babelrc for correct spelling.

error Error: Option "projectPathSuffix" is not supported ↓

cause Using v2 config option from v1

fix

Rename option to "sourceDir" in plugin configuration.

error The import path '~/dir/file.js' was not transformed correctly ↓

cause Missing or incorrect sourceDir configuration

fix

Set sourceDir to project subdirectory (e.g., "src/") so the plugin can compute correct relative path.

error Import with prefix '^' is not being transformed ↓

cause Custom prefix without trailing slash, but import path also lacks slash

fix

If prefix is '^', use '^/dir/file' or change prefix to '^/'.

error Windows: paths contain backslashes ↓

cause Plugin uses forward slashes; Babel might produce backslashes

fix

Ensure Babel config normalizes paths or use a post-transform step.

Warnings

breaking Option `projectPathSuffix` renamed to `sourceDir` in v2 ↓

fix Rename option to `sourceDir` in Babel config.

breaking Option `importPathPrefix` no longer auto-adds trailing slash in v2 ↓

fix If you need a slash, include it in the prefix value (e.g., '^/').

gotcha Webpack users may not need this plugin; use resolve.alias instead ↓

fix Consider using Webpack's resolve.alias for similar behavior without Babel transform.

gotcha Plugin only transforms imports with prefix; other imports left untouched ↓

fix Ensure your project-relative imports use the configured prefix (default: '~/').

deprecated Not actively maintained; last release in 2019 ↓

fix Consider migrating to modern alternatives like babel-plugin-module-resolver.

Install

npm install babel-project-relative-import

yarn add babel-project-relative-import

pnpm add babel-project-relative-import

Imports

default
wrong
```
import plugin from 'babel-project-relative-import';
```
correct
```
module.exports = require('babel-project-relative-import');
```
This is a Babel plugin, not a regular module. It is used via Babel config, not imported directly in source code.

plugin config

wrong

plugins: ['babel-project-relative-import']

correct

plugins: [['babel-project-relative-import', { sourceDir: 'src/', importPathPrefix: '~' }]]

Options are optional. Without options, uses default prefix '~' and no sourceDir.

import with prefix
wrong
```
import Test from '~otherdir/example.js';
```
correct
```
import Test from '~/otherdir/example.js';
```
The default prefix includes a slash. If you set a custom prefix like '^', you need to include the slash manually in the import.

Quickstart

Shows installation, Babel config, and transformation of a project-relative import.

// Install
npm install babel-project-relative-import

// .babelrc
{
  "plugins": [
    "babel-project-relative-import"
  ]
}

// Source file: src/app/index.js
import Helper from '~/lib/helper.js';
console.log(Helper);

// After Babel transform, output becomes:
// import Helper from './../lib/helper.js';