{"id":19354,"library":"babel-project-relative-import","title":"babel-project-relative-import","description":"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.","status":"maintenance","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/per2plex/babel-project-relative-import","tags":["javascript","babel","path","import","relative","project","root","windows"],"install":[{"cmd":"npm install babel-project-relative-import","lang":"bash","label":"npm"},{"cmd":"yarn add babel-project-relative-import","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-project-relative-import","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a Babel plugin, not a regular module. It is used via Babel config, not imported directly in source code.","wrong":"import plugin from 'babel-project-relative-import';","symbol":"default","correct":"module.exports = require('babel-project-relative-import');"},{"note":"Options are optional. Without options, uses default prefix '~' and no sourceDir.","wrong":"plugins: ['babel-project-relative-import']","symbol":"plugin config","correct":"plugins: [['babel-project-relative-import', { sourceDir: 'src/', importPathPrefix: '~' }]]"},{"note":"The default prefix includes a slash. If you set a custom prefix like '^', you need to include the slash manually in the import.","wrong":"import Test from '~otherdir/example.js';","symbol":"import with prefix","correct":"import Test from '~/otherdir/example.js';"}],"quickstart":{"code":"// Install\nnpm install babel-project-relative-import\n\n// .babelrc\n{\n  \"plugins\": [\n    \"babel-project-relative-import\"\n  ]\n}\n\n// Source file: src/app/index.js\nimport Helper from '~/lib/helper.js';\nconsole.log(Helper);\n\n// After Babel transform, output becomes:\n// import Helper from './../lib/helper.js';","lang":"javascript","description":"Shows installation, Babel config, and transformation of a project-relative import."},"warnings":[{"fix":"Rename option to `sourceDir` in Babel config.","message":"Option `projectPathSuffix` renamed to `sourceDir` in v2","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If you need a slash, include it in the prefix value (e.g., '^/').","message":"Option `importPathPrefix` no longer auto-adds trailing slash in v2","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Consider using Webpack's resolve.alias for similar behavior without Babel transform.","message":"Webpack users may not need this plugin; use resolve.alias instead","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your project-relative imports use the configured prefix (default: '~/').","message":"Plugin only transforms imports with prefix; other imports left untouched","severity":"gotcha","affected_versions":"all"},{"fix":"Consider migrating to modern alternatives like babel-plugin-module-resolver.","message":"Not actively maintained; last release in 2019","severity":"deprecated","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install babel-project-relative-import --save-dev` and check .babelrc for correct spelling.","cause":"Plugin not installed or typo in package name","error":"Cannot find module 'babel-project-relative-import'"},{"fix":"Rename option to \"sourceDir\" in plugin configuration.","cause":"Using v2 config option from v1","error":"Error: Option \"projectPathSuffix\" is not supported"},{"fix":"Set sourceDir to project subdirectory (e.g., \"src/\") so the plugin can compute correct relative path.","cause":"Missing or incorrect sourceDir configuration","error":"The import path '~/dir/file.js' was not transformed correctly"},{"fix":"If prefix is '^', use '^/dir/file' or change prefix to '^/'.","cause":"Custom prefix without trailing slash, but import path also lacks slash","error":"Import with prefix '^' is not being transformed"},{"fix":"Ensure Babel config normalizes paths or use a post-transform step.","cause":"Plugin uses forward slashes; Babel might produce backslashes","error":"Windows: paths contain backslashes"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}