gatsby-plugin-root-import

Set Webpack to resolve root, allowing you to import modules from an absolute project path rather than relative ../../ paths.

Install

1. Install the gatsby-plugin-root-import plugin:

   npm install --save-dev gatsby-plugin-root-import

   or

   yarn add --dev gatsby-plugin-root-import

Usage

Add into gatsby-config.js.

// gatsby-config.js

module.exports = {
  plugins: [
    'gatsby-plugin-root-import'
  ]
}

Default Settings

Webpack v4 drops resolve.root in favor of resolve.alias found here.

If no options are specified, the plugin creates a default alias of src to your project src folder.

This means you should be able to import modules like such:

// importing gatsbyProject/src/yourFolder/YourComponent.js

import YourComponent from 'src/yourFolder/YourComponent'

Plugin Options

You can pass as many keys as you want into the plugin options, and they will map to Webpack’s alias configuration.

alias takes an object with keys of your alias names, and values of directory strings like so.

// gatsby-config.js
const path = require('path')

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-root-import',
      options: {
        src: path.join(__dirname, 'src'),
        pages: path.join(__dirname, 'src/pages')
      }
    }
  ]
}

This means you should be able to import modules like such:

// from the 'src' alias
// importing gatsbyProject/src/yourFolder/YourComponent.js

import YourComponent from 'src/yourFolder/YourComponent'

// from the 'pages' alias
// importing gatsbyProject/src/pages/YourPage.js

import YourPage from 'pages/YourPage'

Jest testing

The new aliased paths lets Webpack correctly compile your app. However this does not mean that Jest, or other test runners will understand where those aliases point to.

When setting up testing with Jest, see moduleNameMapper to correctly map your your aliases to a path that Jest can understand.

For example:

// gatsby-config.js
const path = require('path')

module.exports = {
  // ...other configs
  plugins: [
    {
      resolve: 'gatsby-plugin-root-import',
      options: {
        components: path.join(__dirname, 'src/web/components')
      }
    }
  ]
}

could work with a Jest map like:

// jest.config.js
module.exports = {
  // ...other configs
  moduleNameMapper: {
    '^components/(.*)': '<rootDir>/src/web/components/$1',
  }
}

Please see Jest’s moduleNameMapper documentation for specific implementation details regarding format and options.

// gatsby-config.js

module.exports = {
  plugins: [
    'gatsby-plugin-root-import'
  ]
}

// importing gatsbyProject/src/yourFolder/YourComponent.js

import YourComponent from 'src/yourFolder/YourComponent'

// gatsby-config.js
const path = require('path')

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-root-import',
      options: {
        root: path.join(__dirname, 'src')
      }
    }
  ]
}

// importing gatsbyProject/src/yourFolder/YourComponent.js

import YourComponent from 'yourFolder/YourComponent'