Gatsby: The Definitive Guide

Appendix C. Gatsby Configuration APIs

Gatsby provides several configuration APIs that are used to allow for arbitrary configuration of your Gatsby site as well as to adjust how the site works in the browser and how it is handled during server-side rendering and the build process. In this appendix, we’ll take a tour of Gatsby’s Config and Node APIs.

Note

Gatsby also provides other APIs, namely its Browser APIs (to modify Gatsby’s behavior in the browser) and Server-Side Rendering APIs (to modify Gatsby’s server-side rendering behavior), as well as actions and Node API helpers that are outside the scope of these appendixes.

Config APIs

The gatsby-config.js file defines your site’s metadata, plugins, and other broad configuration and must be located in the root directory of your Gatsby site. All sites created with the gatsby new command come with a Gatsby configuration file already populated on your behalf.

The file should export a JavaScript object containing a variety of configuration options, as seen in the following example:

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: `Gatsby`,
  },
  plugins: [
    `gatsby-transform-plugin`,
    {
      resolve: `gatsby-plugin-name`,
      options: {
        optionA: true,
        optionB: `Another option`,
      },
    },
  ],
}

The Gatsby configuration file allows the following configuration options to be set, which are defined in this section:

• siteMetadata (object)

• plugins (array)

• flags (object)

• pathPrefix (string)

• polyfill (Boolean)

• mapping (object)

• proxy ...