Registry / web-framework / gatsby-plugin-root-import

gatsby-plugin-root-import

library2.0.9jsnpmunverified

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.

web-framework

npm install gatsby-plugin-root-import

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-PLUGIN-ROOT

gatsby-plugin-root-import

web-frameworkjavascriptv2.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gatsby-plugin-root-import

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

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

Plugin string form is recommended when no options are needed.

resolveModules

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

✗ Providing resolveModules as a non-array string

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

Custom aliases

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

✗ Setting options as array instead of object

Any key other than resolveModules becomes a Webpack alias.

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';

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

deprecatedThe 'root' option from v1 is deprecated in v2.

fix

Use 'resolveModules' option instead to specify directories.

affects: >=2.0.0

gotchaAliases 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.

affects: >=2.0.0

gotchaJest does not automatically resolve aliases; requires manual moduleNameMapper configuration.

fix

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

affects: >=2.0.0

gotchaMultiple plugins affecting resolve.modules may conflict; order in plugins array matters.

fix

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

affects: >=2.0.0

Errors

Common errors & fixes

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

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.

Cannot find module 'utils/SomeComponent'

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).

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

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

fix

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

Cannot read property 'resolve' of undefined

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: {...} }

Upgrade

Version history

2.0.9latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency; plugin requires Gatsby CLI and build pipeline (version ^2 || ^3 || ^4 || ^5).

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mongkuen/gatsby-plugin-root-import ↗

packagehttps://www.npmjs.com/package/gatsby-plugin-root-import ↗