{"id":20052,"library":"gatsby-alias-imports","title":"gatsby-alias-imports","description":"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.","status":"maintenance","version":"1.0.6","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/luanbitar/gatsby-alias-imports","tags":["javascript","gatsby","gatsby-plugin","alias","import","plugin","aliases","webpack","DefinePlugin"],"install":[{"cmd":"npm install gatsby-alias-imports","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-alias-imports","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-alias-imports","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required as the plugin extends Gatsby's webpack configuration","package":"gatsby","optional":false}],"imports":[{"note":"Plugins are added as strings in gatsby-config.js; importing as an ES module is incorrect.","wrong":"import gatsbyAliasImports from 'gatsby-alias-imports'","symbol":"default plugin import","correct":"module.exports = { plugins: [`gatsby-alias-imports`] }"},{"note":"Gatsby plugins expect object syntax with resolve and options keys; an array tuple is not supported.","wrong":"module.exports = { plugins: [['gatsby-alias-imports', { aliases: { Foo: `src/Foo` } }]] }","symbol":"plugin with options","correct":"module.exports = { plugins: [{ resolve: `gatsby-alias-imports`, options: { aliases: { Foo: `src/Foo` } } }] }"},{"note":"Aliases work with file extensions omitted; including them may cause resolution failures depending on webpack config.","wrong":"import Header from 'components/Header.tsx'","symbol":"TypeScript usage","correct":"import Header from 'components/Header'"}],"quickstart":{"code":"// gatsby-config.js\nmodule.exports = {\n  plugins: [\n    `gatsby-alias-imports`,\n    {\n      resolve: `gatsby-alias-imports`,\n      options: {\n        aliases: {\n          styles: `src/styles`,\n          components: `src/components`,\n          utils: `src/utils`\n        }\n      }\n    }\n  ]\n};\n// Then in any file:\nimport Header from 'components/Header';\nimport 'styles/main.css';","lang":"javascript","description":"Shows how to configure the plugin with custom aliases and use them in imports."},"warnings":[{"fix":"Set resolve.symlinks: true in gatsby-node.js via onCreateWebpackConfig if you experience cryptic import errors.","message":"Plugin uses resolve.symlinks: false by default, which may break node_modules resolution in linked packages or workspaces.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Consider migrating to native Gatsby path mapping or other maintained plugins like gatsby-plugin-alias-imports.","message":"No updates since 2019; does not support Gatsby v5 (requires Gatsby >2.0.0 but untested with newer versions).","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Use paths relative to project root, e.g., 'src/Foo' instead of '/absolute/path/to/src/Foo'.","message":"All values in options.aliases must be relative paths (e.g., 'src/styles'), not absolute paths starting with '/' or '../'.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure all alias paths are relative to rootFolder, not src. Update aliases accordingly.","message":"If rootFolder is not set, the plugin assumes '/src' as default root. Changing rootFolder may break existing aliases if they contain '/src'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add `gatsby-alias-imports` to plugins array and verify alias path is relative to root (e.g., 'src/components').","cause":"Aliased import not resolved because plugin not added to gatsby-config.js or alias path is incorrect.","error":"Error: Cannot find module 'components/Header'"},{"fix":"Use { resolve: `gatsby-alias-imports`, options: { ... } }.","cause":"Plugin configuration uses array syntax (e.g., ['gatsby-alias-imports', options]) instead of object syntax.","error":"You cannot use the package [object Object] as a Gatsby plugin"},{"fix":"Either omit options entirely or supply an aliases object. If using default behavior, simply add `gatsby-alias-imports` as a string.","cause":"Plugin added without options but code expects aliases object; occurs if plugin source has a bug or misconfiguration.","error":"TypeError: Cannot read property 'aliases' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}