Gatsby config.js

In this section we cover the settings that are configurable in the config.js file located in the root of your project.

You don't necessarily need to edit the config.js in order to have your site running. However, you will need to edit it if you want to do things like:

• adding Google Analytics or Google Tag Manager,
• activating the XML sitemap for your site,
• pass settings to the gatsby-source-wordpress plugin that we use internally.

Let's first have a look at the list of options with their default values. Below, we discuss each one in detail.

Copy
const config = {
  pathPrefix: "",
  webfontsOptions: {},
  gaTrackingId: 0,
  gaOptions: {},
  googleTagManagerId: 0,
  googleTagManagerOptions: {},
  addSiteMap: false,
  siteMapOptions: {},
  developLimit: null,
  gatsbySourceWordPressOptions: {},
  createPages: true,
  createPosts: true,
  createCategories: true,
  createTags: true,
  createUsers: true,
  withApollo: true,
}
module.exports = config

Besides that, in the config.js file, you can override some of the settings coming from your WordPress source site. Please head to the Overriding WordPress Theme Options for more details.

Let's now discuss the available settings.

pathPrefix

optional, default: ""

Typically, your Gatsby website will be hosted at the root of its domain. In that case, the pathPrefix is an empty string, and you can skip this setting. You will only need to set the pathPrefix if your gatsby website is hosted at something other than the root (/), e.g., https://example.com/demo.

Adding the path prefix requires two steps:

Sometimes, you might want to access your production site locally. In that case, you will have to serve it with the --prefix-paths flag, i.e., gatsby serve --prefix-paths Your production build will be available at http://localhost:9000/demo.

webfontsOptions

Our themes support Google web fonts, under the hood we use the Gatsby plugin gatsby-plugin-webfonts. The webfontsOptions setting is passed to the gatsby-plugin-webfonts options.

Let's imagine that you want to use Abril Fatface for headings and Lora for the body.

Copy
const config = {
  // ...
  webfontsOptions: {
    fonts: {
      google: [
        { family: "Abril Fatface" },
        {
          family: "Lora",
          variants: ["400", "400i", "700", "700i"],
        },
      ],
    },
  },
  // ...
}
module.exports = config

Now Abril Fatface and Lora (in the specified variants) are loaded and available in your project. You still have to specify how you want to use them in the tailwind.config.js file :

Copy
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        body: "Lora, serif",
        heading: "Abril Fatface,serif",
      },
      fontWeight: {
        body: 400,
        heading: "bold",
        bold: 700,
      },
      lineHeight: {
        body: 1.8,
        heading: 1.4,
        loose: 2,
      },
    },
  },
}

If other options are not specified, the plugin defaults are as follows :

Copy
formats: ["woff2", "woff"],
useMinify: true,
usePreload: true,
usePreconnect: false,
formatAgents: {
  eot: `Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; .NET4.0C; .NET4.0E)`,
  ttf: `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/534.59.8 (KHTML, like Gecko) Version/5.1.9 Safari/534.59.8`,
  woff: `Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729; rv:11.0) like Gecko`,
  woff2: `Mozilla/5.0 (Windows NT 10.0; Win64; x64; ServiceUI 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36 Edge/14.14393`,
},

gaTrackingId

optional, type: string

You can add Google Analytics to your Gatsby site by providing your Google Analytics tracking ID. Also, please note that the Google Analytics functionality is disabled in the development mode.

Copy
const config = {
  // ...
  gaTrackingId: "G-XXXXXXXXXX",
  // ...
}
module.exports = config

gaOptions

optional, default: {}

Under the hook we use the official Gatsby plugin gatsby-plugin-google-gtag, and you can pass here any of its options.

Copy
const config = {
  // ...
  gaTrackingId: "G-XXXXXXXXXX",
  gaOptions: {
    pluginConfig: {
      head: true,
    },
  },
  // ...
}
module.exports = config

googleTagManagerId

optional, default: 0

Your Google Tag Manager Id. This option is passed to the gatsby plugin 'gatsby-plugin-google-tagmanager'. You can pass any additional available settings with googleTagManagerOptions.

Copy
const config = {
  googleTagManagerId: "GTM-XXXXXX",
  // ...
}
module.exports = config

googleTagManagerOptions

optional, default: {}

As mentioned above, we use gatsby-plugin-google-tagmanager under the hood. Any options that you add here will be passed to the plugin options - please refer to the plugin documentation for further details and available options.

Copy
const config = {
  googleTagManagerId: "GTM-XXXXXX",
  googleTagManagerOptions: {
    includeInDevelopment: false,
    defaultDataLayer: function () {
      return {
        pageType: window.pageType,
      }
    },
  },
  // ...
}
module.exports = config

addSiteMap

optional, type: boolean, default: false

Setting addSiteMap to true will generate a site map for your website.

The site map will be generated only when run in production mode.

Copy
const config = {
  // ...
  addSiteMap: true,
  // ...
}
module.exports = config

Please note that your site map will list absolute URLs to your pages. That means you have to provide your production gatsby website URL as the value for GATSBY_SITE_URL in your .env file (see Setting up the .env File).

siteMapOptions

optional, default: {}

The siteMapOptions setting is only used if addSiteMap is set true. The siteMapOptions are passed to the gatsby-plugin-sitemap options so please refer to gatsby-plugin-sitemap options for the details. Pass any options that you would pass to the gatsby-plugin-sitemap options to siteMapOptions.

You don't have to worry about passing siteUrl to siteMetadata (as stated in the plugin documentation) - we take care of that, just make sure to provide GATSBY_SITE_URL in your .env file (see Setting up the .env File).

Copy
const config = {
  // ...
  addSiteMap: true,
  siteMapOptions: {
    excludes: ["/contact/"],
  },
  // ...
}
module.exports = config

developLimit

optional, default: null

If you work on a big website, you might not need to fetch all the data during the development. The developLimit lets you limit the maximum amount of objects of each type that are fetched from WordPress.

Copy
const config = {
  // ...
  developLimit: 3,
  // ...
}
module.exports = config

gatsbySourceWordPressOptions

optional, default: {}

Our themes internally use the gatsby-source-wordpress plugin that sources data from WordPress. With the gatsbySourceWordPressOptions setting you can pass options to this plugin. You can find the overview of the available options here.

Copy
const config = {
  // ...
  gatsbySourceWordPressOptions: {
    schema: {
      perPage: 10,
    },
    type: {
      MediaItem: {
        localFile: {
          requestConcurrency: 50,
        },
      },
    },
  },
  // ...
}
module.exports = config

createPages

optional, default: true

With createPages: false, you can deactivate creating routes for the static pages fetched from the WordPress. Since the pages will not be created, make sure that your site does not link to them internally. In particular, you should not have links to pages withing your navigation menu.

createPosts, createCategories, createTags, createUsers

optional, default: true

These options work alike createPages described above, each of them applying to their particular type of content.

withApollo

optional, default: true

If you modify this option, make sure to provide some alternative for the Apollo Client that we're using internally. Otherwise your website may not work correctly.