gatsby-plugin-root-import

2.0.9 verified Sat Apr 25 auth: no javascript maintenance

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.

Common errors

error Module not found: Can't resolve 'src/...' ↓

cause Plugin default root is 'src' but you're missing 'src/' prefix in import.

fix

Either add 'src/' to import path, or configure resolveModules to include project root.

error Cannot find module 'utils/SomeComponent' ↓

cause Alias defined but path is incorrect or file does not exist.

fix

Verify the alias path in gatsby-config.js using absolute path (path.join).

error Plugin gatsby-plugin-root-import is not compatible with gatsby version X. ↓

cause Peer dependency only supports Gatsby ^2 || ^3 || ^4 || ^5.

fix

Use compatible Gatsby version or remove plugin if using newer Gatsby.

error Cannot read property 'resolve' of undefined ↓

cause Options object passed without 'resolve' key; correct format has 'resolve' key for plugin name.

fix

Use the correct format: { resolve: 'gatsby-plugin-root-import', options: {...} }

Warnings

breaking Version 2.0.0 changed default root from project root to 'src' folder. ↓

fix Update imports to include 'src/' prefix or configure root explicitly. For old behavior, set resolveModules to project root.

deprecated The 'root' option from v1 is deprecated in v2. ↓

fix Use 'resolveModules' option instead to specify directories.

gotcha Aliases are case-sensitive on some file systems (Linux). Inconsistent casing causes Webpack resolution failures. ↓

fix Ensure all alias paths use consistent case matching actual file system.

gotcha Jest does not automatically resolve aliases; requires manual moduleNameMapper configuration. ↓

fix Add matching moduleNameMapper entries in Jest config as described in plugin README.

gotcha Multiple plugins affecting resolve.modules may conflict; order in plugins array matters. ↓

fix Place gatsby-plugin-root-import early in plugins array or consolidate configurations.

Install

npm install gatsby-plugin-root-import

yarn add gatsby-plugin-root-import

pnpm add gatsby-plugin-root-import

Imports

gatsby-plugin-root-import

wrong

Using require() in gatsby-config.js for plugin string (though require is allowed for options, the string form is simpler)

correct

plugins: ['gatsby-plugin-root-import']

Plugin string form is recommended when no options are needed.

resolveModules

wrong

Providing resolveModules as a non-array string

correct

options: { resolveModules: [path.join(__dirname, 'libs')] }

This option adds directories to Webpack's resolve.modules.

Custom aliases

wrong

Setting options as array instead of object

correct

options: { utils: path.join(__dirname, 'src/components/utilities') }

Any key other than resolveModules becomes a Webpack alias.

Quickstart

Shows how to configure the plugin with custom resolveModules and aliases in gatsby-config.js, then import using the alias.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-root-import',
      options: {
        resolveModules: [path.join(__dirname, 'libs')],
        utils: path.join(__dirname, 'src', 'components', 'utilities'),
      },
    },
  ],
};
// Then use in any component:
import UtilityComponent from 'utils/UtilityComponent';