/* Code-Comments */

August 30, 2019

Import Aliases in Gatsby

I wanted to be able to import JSX elements I defined in a Gatsby project into markdown files.

Very quickly I got tired of writing out the absolute paths:

import Component from '../../../src/Shared/Component'

Ideally, it would be much simpler:

import Component from 'Shared/Component'

Shared communicates immediately that it’s a locally defined component.

I found a great step-by-step tutorial from Jan Hrubý @ Mrozilla which walked me through the steps.1

Jan’s tutorial walks through configuring Gatsby’s Webpack (at least as much as we’re able to since Gatsby doesn’t expose the config file for changes), ESlint, and VSCode’s auto complete.

I didn’t have his issues with ESlint, so I was able to skip that step.

Configuring Gatsby’s Webpack

While Gatsby doesn’t expose its Webpack configuration, they do provide an onCreateWebpackConfig hook that can be customized within gatsby-node.js.

Using the hook, we can add a resolver object, just as we would within a webpack.config.js.

For example, here’s a webpack.config.js file I have from another project:

Const path = require(‘path’);

module.exports = {
    commonResolve: {
        alias: {
            /* [...] */
            Shared: path.resolve(__dirname, ‘src/Shared’),
            /* [...] */

In a Gatsby project, add the following lines to the gatsby-node.js:

const path = require('path')

exports.onCreateWebpackConfig = ({ actions }) => {
    resolve: {
      alias: {
        Shared: path.resolve(__dirname, 'src/Shared'),

The Gatsby docs also note other ways you may want to modify the Webpack config.2


Stephen Weiss

Thanks for reading! My name's Stephen Weiss. I live in Chicago with my wife, Kate, and dog, Finn.
Click here to see the archives of my weeks in review and sign up yourself!