Webpack

As a Gatsby developer, you should attempt a custom Webpack configuration only if the default Webpack configuration built into Gatsby does not support your requirements and there is no Gatsby plugin available in the ecosystem that meets your needs. For those cases, Gatsby provides a Node API known as onCreateWebpackConfig that can be implemented in gatsby-node.js to adjust the default Gatsby Webpack configuration.

When Gatsby generates its own Webpack configuration during the build lifecycle, it will use the webpack-merge library to combine the two configurations together appropriately. We’ll dig into the details of how Gatsby performs Webpack builds in the final section of this app, but for now one of the most important concepts to understand about Webpack use in Gatsby is that distinct builds are generated based on each build type or stage, of which four exist:developThis stage occurs when you execute the gatsby develop command, and the Webpack configuration includes settings for hot reloading and in-page CSS injection to aid development.develop-htmlThis is identical to the previous stage but is responsible for rendering the HTML component, which represents the outermost component of a Gatsby site (see also the next section).build-javascriptThis stage is responsible for the production JavaScript and CSS build, including the creation of route-specific JavaScript bundles and common Webpack chunks for JavaScript and CSS assets.build-htmlThis stage represents the production build that yields static HTML pages.

For an example of customizing Webpack configuration using the onCreateWebpackConfig API, consider the following code that incorporates the less-loader plugin for LESS stylesheet files requiring compilation:

// gatsby-node.js
exports.onCreateWebpackConfig = ({
  stage,
  rules,
  loaders,
  plugins,
  actions,
}) => {
  actions.setWebpackConfig({
    module: {
      rules: [
        {
          test: /\.less$/,
          use: [
            // You don't need to add the matching ExtractText plugin
            // because Gatsby already includes it and makes sure it's only
            // run at the appropriate stages, e.g. not in development
            loaders.miniCssExtract(),
            loaders.css({ importLoaders: 1 }),
            // The postcss loader comes with some nice defaults
            // including autoprefixer for our configured browsers
            loaders.postcss(),
            `less-loader`,
          ],
        },
      ],
    },
    plugins: [
      plugins.define({
        __DEVELOPMENT__: stage === `develop` || stage === `develop-html`,
      }),
    ],
  })
}

Another common use case, particularly for repetitive references to components in import statements, is to set the Webpack configuration to permit absolute imports in order to avoid specifying paths each and every time you import the components. For instance, consider the following example API implementation in gatsby-node.js:

// gatsby-node.js
exports.onCreateWebpackConfig = ({ stage, actions }) => {
  actions.setWebpackConfig({
    resolve: {
      modules: [path.resolve(__dirname, "src"), "node_modules"],
    },
  })
}

Instead of writing the following in Gatsby components:

import Footer from '../../components/footer'

you can write the following after adjusting the Webpack configuration accordingly:

import Footer from 'components/footer'

NOTE

For more information about other advanced use cases involving the customization of Gatsby’s default Webpack configuration, consult the Gatsby documentation on importing non-Webpack tools using Yarn and modifying the Babel loader.