{"id":18977,"library":"babel-7-plugin-root-import","title":"babel-plugin-root-import","description":"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).","status":"active","version":"5.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/entwicklerstube/babel-plugin-root-import","tags":["javascript"],"install":[{"cmd":"npm install babel-7-plugin-root-import","lang":"bash","label":"npm"},{"cmd":"yarn add babel-7-plugin-root-import","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-7-plugin-root-import","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for plugin resolution.","package":"@babel/core","optional":false}],"imports":[{"note":"This is a Babel plugin, not a runtime library. It is configured in .babelrc or babel.config.js, not imported in application code.","wrong":"import plugin from 'babel-plugin-root-import'; // not a runtime import","symbol":"plugin","correct":"// .babelrc: \"plugins\": [\"babel-plugin-root-import\"]"},{"note":"The correct option key is 'rootPathPrefix', not 'prefix' or 'rootPrefix'. This is a common typo.","wrong":"{\n  \"plugins\": [\n    [\"babel-plugin-root-import\", { \"prefix\": \"@\" }]\n  ]\n}","symbol":"options: rootPathPrefix","correct":"{\n  \"plugins\": [\n    [\"babel-plugin-root-import\", { \"rootPathPrefix\": \"@\" }]\n  ]\n}"},{"note":"The correct option key is 'rootPathSuffix', not 'suffix'. If not set, the root defaults to the project directory.","wrong":"{\n  \"plugins\": [\n    [\"babel-plugin-root-import\", { \"suffix\": \"src\" }]\n  ]\n}","symbol":"options: rootPathSuffix","correct":"{\n  \"plugins\": [\n    [\"babel-plugin-root-import\", { \"rootPathSuffix\": \"src\" }]\n  ]\n}"}],"quickstart":{"code":"npm install --save-dev babel-plugin-root-import\n\necho '{\n  \"plugins\": [\n    [\"babel-plugin-root-import\", {\n      \"rootPathSuffix\": \"src\"\n    }]\n  ]\n}' > .babelrc\n\n# Create an example file\nmkdir -p src/utils\ncat > src/index.js << 'EOF'\nimport { helper } from '~/utils/helper';\nconsole.log(helper);\nEOF\ncat > src/utils/helper.js << 'EOF'\nexport const helper = 'Hello from root import!';\nEOF\n\n# Run with babel-node\nnpx babel-node src/index.js\n# Output: Hello from root import!","lang":"javascript","description":"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."},"warnings":[{"fix":"Update your .babelrc to use 'babel-plugin-root-import' instead of 'babel-root-import'.","message":"Version 5.0.0 changed the plugin name from 'babel-root-import' to 'babel-plugin-root-import'.","severity":"breaking","affected_versions":"<5.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add 'import/resolver' configuration in your ESLint config: {\"babel-plugin-root-import\": {}}","message":"When using ESLint with eslint-plugin-import, root imports will be flagged as unresolved unless you configure eslint-import-resolver-babel-root-import.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Explicitly set 'rootPathSuffix' to the directory relative to which you want root imports to resolve (e.g., 'src').","message":"The '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.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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).","cause":"The plugin is not configured correctly or the root path suffix does not lead to the correct directory.","error":"Module not found: Can't resolve '~/components/Header'"},{"fix":"Change 'rootPrefix' to 'rootPathPrefix' in your .babelrc options.","cause":"Typo in option name: 'rootPrefix' instead of 'rootPathPrefix'.","error":"Error: Plugin 0 specified in \"...\" provided an invalid property of \"rootPrefix\""},{"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.","cause":"You have installed a version of babel-plugin-root-import that requires Babel 7 but your project uses Babel 6.","error":"Error: Requires Babel \"^7.0.0-0\", but was loaded with \"6.26.3\""}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}