Registry / web-framework / gatsby-alias-imports

gatsby-alias-imports

library1.0.6jsnpmunverified

A Gatsby plugin that provides Webpack resolve aliasing for import statements, simplifying paths by mapping folders (default: all src subdirectories) to short aliases. Version 1.0.6 is the current stable release, with no active development observed since 2019. It works with Gatsby >2.0.0 and offers optional custom alias and root folder configuration. Unlike manual webpack configuration in gatsby-node.js, this plugin automates alias setup without additional boilerplate.

web-framework

npm install gatsby-alias-imports

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-ALIAS-IMPOR

gatsby-alias-imports

web-frameworkjavascriptv1.0.6

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.

default plugin import

✓ module.exports = { plugins: [`gatsby-alias-imports`] }

✗ import gatsbyAliasImports from 'gatsby-alias-imports'

Plugins are added as strings in gatsby-config.js; importing as an ES module is incorrect.

plugin with options

✓ module.exports = { plugins: [{ resolve: `gatsby-alias-imports`, options: { aliases: { Foo: `src/Foo` } } }] }

✗ module.exports = { plugins: [['gatsby-alias-imports', { aliases: { Foo: `src/Foo` } }]] }

Gatsby plugins expect object syntax with resolve and options keys; an array tuple is not supported.

TypeScript usage

✓ import Header from 'components/Header'

✗ import Header from 'components/Header.tsx'

Aliases work with file extensions omitted; including them may cause resolution failures depending on webpack config.

Shows how to configure the plugin with custom aliases and use them in imports.

// gatsby-config.js module.exports = { plugins: [ `gatsby-alias-imports`, { resolve: `gatsby-alias-imports`, options: { aliases: { styles: `src/styles`, components: `src/components`, utils: `src/utils` } } } ] }; // Then in any file: import Header from 'components/Header'; import 'styles/main.css';

Debug

Known issues

breakingPlugin uses resolve.symlinks: false by default, which may break node_modules resolution in linked packages or workspaces.

fix

Set resolve.symlinks: true in gatsby-node.js via onCreateWebpackConfig if you experience cryptic import errors.

affects: >=1.0.0

deprecatedNo updates since 2019; does not support Gatsby v5 (requires Gatsby >2.0.0 but untested with newer versions).

fix

Consider migrating to native Gatsby path mapping or other maintained plugins like gatsby-plugin-alias-imports.

affects: >=1.0.0

breakingAll values in options.aliases must be relative paths (e.g., 'src/styles'), not absolute paths starting with '/' or '../'.

fix

Use paths relative to project root, e.g., 'src/Foo' instead of '/absolute/path/to/src/Foo'.

affects: >=1.0.0

gotchaIf rootFolder is not set, the plugin assumes '/src' as default root. Changing rootFolder may break existing aliases if they contain '/src'.

fix

Ensure all alias paths are relative to rootFolder, not src. Update aliases accordingly.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'components/Header'

Aliased import not resolved because plugin not added to gatsby-config.js or alias path is incorrect.

fix

Add `gatsby-alias-imports` to plugins array and verify alias path is relative to root (e.g., 'src/components').

You cannot use the package [object Object] as a Gatsby plugin

Plugin configuration uses array syntax (e.g., ['gatsby-alias-imports', options]) instead of object syntax.

fix

Use { resolve: `gatsby-alias-imports`, options: { ... } }.

TypeError: Cannot read property 'aliases' of undefined

Plugin added without options but code expects aliases object; occurs if plugin source has a bug or misconfiguration.

fix

Either omit options entirely or supply an aliases object. If using default behavior, simply add `gatsby-alias-imports` as a string.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency required as the plugin extends Gatsby's webpack configuration

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/luanbitar/gatsby-alias-imports ↗

packagehttps://www.npmjs.com/package/gatsby-alias-imports ↗