{"id":20053,"library":"gatsby-plugin-root-import","title":"gatsby-plugin-root-import","description":"Gatsby plugin that configures Webpack to resolve modules from absolute paths, eliminating relative `../../` imports. Latest v2.0.9 supports Gatsby v2 through v5 via peer dependencies. Key differentiator: provides automatic `src` resolution without options, plus custom aliases and `resolveModules` for additional directories. Maintenance mode as of 2023; no active development but stable. Alternative: use Gatsby's native `resolve.alias` via Webpack config in `gatsby-node.js` for more control.","status":"maintenance","version":"2.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/mongkuen/gatsby-plugin-root-import","tags":["javascript","gatsby","gatsby-plugin","import","root"],"install":[{"cmd":"npm install gatsby-plugin-root-import","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-plugin-root-import","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-plugin-root-import","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin requires Gatsby CLI and build pipeline (version ^2 || ^3 || ^4 || ^5).","package":"gatsby","optional":false}],"imports":[{"note":"Plugin string form is recommended when no options are needed.","wrong":"Using require() in gatsby-config.js for plugin string (though require is allowed for options, the string form is simpler)","symbol":"gatsby-plugin-root-import","correct":"plugins: ['gatsby-plugin-root-import']"},{"note":"This option adds directories to Webpack's resolve.modules.","wrong":"Providing resolveModules as a non-array string","symbol":"resolveModules","correct":"options: { resolveModules: [path.join(__dirname, 'libs')] }"},{"note":"Any key other than resolveModules becomes a Webpack alias.","wrong":"Setting options as array instead of object","symbol":"Custom aliases","correct":"options: { utils: path.join(__dirname, 'src/components/utilities') }"}],"quickstart":{"code":"// gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-plugin-root-import',\n      options: {\n        resolveModules: [path.join(__dirname, 'libs')],\n        utils: path.join(__dirname, 'src', 'components', 'utilities'),\n      },\n    },\n  ],\n};\n// Then use in any component:\nimport UtilityComponent from 'utils/UtilityComponent';","lang":"javascript","description":"Shows how to configure the plugin with custom resolveModules and aliases in gatsby-config.js, then import using the alias."},"warnings":[{"fix":"Update imports to include 'src/' prefix or configure root explicitly. For old behavior, set resolveModules to project root.","message":"Version 2.0.0 changed default root from project root to 'src' folder.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use 'resolveModules' option instead to specify directories.","message":"The 'root' option from v1 is deprecated in v2.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Ensure all alias paths use consistent case matching actual file system.","message":"Aliases are case-sensitive on some file systems (Linux). Inconsistent casing causes Webpack resolution failures.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Add matching moduleNameMapper entries in Jest config as described in plugin README.","message":"Jest does not automatically resolve aliases; requires manual moduleNameMapper configuration.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Place gatsby-plugin-root-import early in plugins array or consolidate configurations.","message":"Multiple plugins affecting resolve.modules may conflict; order in plugins array matters.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Either add 'src/' to import path, or configure resolveModules to include project root.","cause":"Plugin default root is 'src' but you're missing 'src/' prefix in import.","error":"Module not found: Can't resolve 'src/...'"},{"fix":"Verify the alias path in gatsby-config.js using absolute path (path.join).","cause":"Alias defined but path is incorrect or file does not exist.","error":"Cannot find module 'utils/SomeComponent'"},{"fix":"Use compatible Gatsby version or remove plugin if using newer Gatsby.","cause":"Peer dependency only supports Gatsby ^2 || ^3 || ^4 || ^5.","error":"Plugin gatsby-plugin-root-import is not compatible with gatsby version X."},{"fix":"Use the correct format: { resolve: 'gatsby-plugin-root-import', options: {...} }","cause":"Options object passed without 'resolve' key; correct format has 'resolve' key for plugin name.","error":"Cannot read property 'resolve' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}