{"id":19162,"library":"babel-plugin-root-import","title":"babel-plugin-root-import","description":"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.","status":"active","version":"6.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/entwicklerstube/babel-plugin-root-import","tags":["javascript"],"install":[{"cmd":"npm install babel-plugin-root-import","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-root-import","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-root-import","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Configuration is passed as the second element of a tuple: [pluginName, options].","wrong":"plugins: ['babel-plugin-root-import', { rootPathPrefix: '~/' }] // wrong: config must be nested array","symbol":"default plugin","correct":"// in babel.config.js\nplugins: ['babel-plugin-root-import']"},{"note":"The plugin transforms source code at build time; no runtime API.","wrong":"const path = require('babel-plugin-root-import').resolve('~/my-module'); // no such API","symbol":"require (CommonJS)","correct":"const path = require('~/my-module');"},{"note":"Template literals in dynamic imports are supported from v6.6.0 onward.","wrong":"import(`~/my-${name}`).then(mod => ...); // template literals supported since v6.6.0, but older versions may fail","symbol":"dynamic import","correct":"import('~/my-module').then(mod => ...);"}],"quickstart":{"code":"// .babelrc\n{\n  \"plugins\": [\n    [\"babel-plugin-root-import\", {\n      \"rootPathPrefix\": \"~/\",\n      \"rootPathSuffix\": \"./src\"\n    }]\n  ]\n}\n\n// file: src/app.js\nimport MyComponent from '~/components/MyComponent';\n// resolves to ./src/components/MyComponent relative to process cwd\n\n// file: src/other.js\nconst utils = require('~/utils/helper');\n// resolves to ./src/utils/helper.js\n\n// dynamic import with template literal (v6.6.0+)\nconst moduleName = 'dashboard';\nimport(`~/pages/${moduleName}`).then(module => {\n  // ...\n});","lang":"javascript","description":"Shows how to configure the plugin with custom prefix and suffix, and use it with static require/import and dynamic import with template literals."},"warnings":[{"fix":"Set rootPathSuffix to './src' (or your source directory) in plugin options.","message":"Default root path suffix is './' so '~/foo' resolves to CWD/foo, not CWD/src/foo. Most users expect ~/ to point to src/.","severity":"gotcha","affected_versions":"all"},{"fix":"Use '~/' or another prefix that does not start with '@'.","message":"The '@' prefix is not recommended as NPM allows '@' in package names and can cause conflicts.","severity":"deprecated","affected_versions":"all"},{"fix":"Upgrade to >=6.2.0 or ensure prefix is at least 2 characters long (excluding slash).","message":"In v6.2.0, the 2-character restriction on rootPathPrefix was removed. Prefixes with fewer than 2 characters now work but may cause unexpected matches.","severity":"breaking","affected_versions":"<6.2.0"},{"fix":"If using a bundler, configure corresponding aliases (e.g., in webpack resolve.alias) to match the root prefix.","message":"The plugin transforms source files only; it does not affect runtime resolution. Webpack or other bundlers may still need separate alias configuration.","severity":"gotcha","affected_versions":"all"},{"fix":"Add equivalent path mappings in tsconfig.json compilerOptions.paths.","message":"When 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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure plugin is in .babelrc plugins array and rootPathSuffix is correct relative to CWD.","cause":"Plugin not configured or not applied; or rootPathSuffix points to wrong directory.","error":"Module not found: Can't resolve '~/something'"},{"fix":"Run 'npm install --save-dev babel-plugin-root-import' or 'yarn add --dev babel-plugin-root-import'.","cause":"Package not installed or missing from node_modules.","error":"Error: Plugin babel-plugin-root-import not found"},{"fix":"Use nested array format: ['babel-plugin-root-import', { rootPathPrefix: '~/' }].","cause":"Misconfigured plugin options; used array or object instead of tuple [name, options].","error":"The 'rootPathPrefix' option must be a string"},{"fix":"Upgrade to v6.6.0 or later, or avoid template literals (use simple string literals).","cause":"Using babel-plugin-root-import version < 6.6.0 which did not support template literals in import() expressions.","error":"Template literals are not supported in dynamic imports with this version"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}