gatsby-alias-imports

1.0.6 verified Sat Apr 25 auth: no javascript maintenance

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.

Common errors

error Error: Cannot find module 'components/Header' ↓

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

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

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

fix

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

error TypeError: Cannot read property 'aliases' of undefined ↓

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

Warnings

breaking Plugin 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.

deprecated No 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.

breaking All 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'.

gotcha If 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.

Install

npm install gatsby-alias-imports

yarn add gatsby-alias-imports

pnpm add gatsby-alias-imports

Imports

default plugin import
wrong
```
import gatsbyAliasImports from 'gatsby-alias-imports'
```
correct
```
module.exports = { plugins: [`gatsby-alias-imports`] }
```
Plugins are added as strings in gatsby-config.js; importing as an ES module is incorrect.

plugin with options

wrong

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

correct

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

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

TypeScript usage
wrong
```
import Header from 'components/Header.tsx'
```
correct
```
import Header from 'components/Header'
```
Aliases work with file extensions omitted; including them may cause resolution failures depending on webpack config.

Quickstart

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