Switch branches/tags
AnushPatel-patch-1 JanoshRiebesell-patch-1 KyleAMathews-patch-1 Partner-program add-depn add-escalade-sports-case-study add-mobile-performance-post add-plugin-documentation alter-blog-post-date amberleyromo-7730-starter-showcase-sourcing amberleyromo-patch-1 array-doclets berrak-responsive-layout blogpost-gatsby-days-preso calcsam-patch-1 ccustom-algolia-index change-hacktoberfest-title config-api coreyward-patch-1-1 cypress-timeouts docs-rename-starter docs/gatsby-remark-images-sharp documentation-project-blogpost-new-title drop-alpha-support filter-css fix-broken-link fix-doc fix-docs-reload fix/starter-detail-dependency-grid fix/typescript-reach-router fixes-to-plugin-library gatsby-ssr-silent-fail graphql-filter-sort gvarandas-patch-1 hu0p-patch-1 imagentleman-patch-1 link-container m-allanson-patch-1 marisamorby-swag-store-post master mikeriley131-patch-1 neo/move-prefixPath old-master-3 old-master-4 old-master-6 old-master-7 page-metadata-splitting plugin-blogpost-edit plugin-cli pr/8963 revert-4254-blog-documentation-project revert-5047-update-remark revert-workspaces rfbotto-patch-1 sample-branch-example sebastienfi-wp-orderby-date-asc shannonbux-docs-contributions sharp-images-no-ext sort-chunks starterShowcase2 style-guide-update styled-components-babelrc-config-doc test-builds topics/gatsby-plugin-sharp-tracesvg-fluid topics/inconsistent-accordian-behavior-docs-sidebar topics/using-gatsby-image-design-refresh topics/www-bump-remark-autolink-headers topics/www-sidebar-move-expand-all-down tryzniak-patch-1 update-imagemin-deps updated-style-guide-tutorial-details v1 v2 valse-disable-default-pageview valse-resolve-env worker
Nothing to show
Find file Copy path
136 lines (113 sloc) 4.51 KB
Add custom webpack config

Before creating custom webpack configuration, check to see if there's a Gatsby plugin already built that handles your use case in the plugins section. If there's not yet one and your use case is a general one, we highly encourage you to contribute back your plugin to the Gatsby Plugin Library so it's available to others (including your future self 😀).

To add custom webpack configurations, create (if there's not one already) a gatsby-node.js file in your root directory. Inside this file, export a function called onCreateWebpackConfig.

When Gatsby creates its webpack config, this function will be called allowing you to modify the default webpack config using webpack-merge.

Gatsby does multiple webpack builds with somewhat different configuration. We call each build type a "stage". The following stages exist:

  1. develop: when running the gatsby develop command. Has configuration for hot reloading and CSS injection into page
  2. develop-html: same as develop but without react-hmre in the babel config for rendering the HTML component.
  3. build-javascript: production JavaScript and CSS build. Creates route JS bundles as well as commons chunks for JS and CSS.
  4. build-html: production build static HTML pages

Check webpack.config.js for the source.

There are many plugins in the Gatsby repo using this API to look to for examples e.g. Sass, TypeScript, Glamor, and many more!


Here is an example adding an additional global variable via the DefinePlugin and the less-loader:

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

Absolute imports

Instead of writing import Header from '../../components/Header' over and over again you can just write import Header from 'components/Header' with absolute imports:

exports.onCreateWebpackConfig = ({ stage, actions }) => {
    resolve: {
      modules: [path.resolve(__dirname, "src"), "node_modules"],

You can always find more information on resolve and other options in the official Webpack docs.

Modifying the babel loader

You need this if you want to do things like transpile parts of node_modules.

exports.onCreateWebpackConfig = ({ actions, loaders, getConfig }) => {
  const config = getConfig()

  config.module.rules = [
    // Omit the default rule where test === '\.jsx?$'
      rule => String(rule.test) !== String(/\.jsx?$/)

    // Recreate it with custom exclude filter
      // Called without any arguments, `loaders.js` will return an
      // object like:
      // {
      //   options: undefined,
      //   loader: '/path/to/node_modules/gatsby/dist/utils/babel-loader.js',
      // }
      // Unless you're replacing Babel with a different transpiler, you probably
      // want this so that Gatsby will apply its required Babel
      // presets/plugins.  This will also merge in your configuration from
      // `babel.config.js`.

      test: /\.jsx?$/,

      // Exclude all node_modules from transpilation, except for 'swiper' and 'dom7'
      exclude: modulePath =>
        /node_modules/.test(modulePath) &&

  // This will completely replace the webpack config with the modified object.