The gatsby-config.js API File
gatsby-config.js defines your site’s metadata, plugins, and other general configuration. This file should be in the root of your Gatsby site.
If you created a Gatsby site with the
gatsby new command, there should already be a sample configuration file in your site’s directory.
gatsby-config.js file could look like this:
There are many configuration options available, but the most common set site-wide metadata and enable plugins.
siteMetadata object can contain any data you want to share across your site. A useful example is the site’s title. If you store the title in
siteMetadata, you can alter the title in one place, and it will be updated throughout your site. To add metadata, include a
siteMetadata object in your configuration file:
You can then access the site title using GraphQL anywhere on your site.
Plugins add new features to your Gatsby site. For example, some plugins fetch data from hosted services, transform data formats, or resize images. The Gatsby plugin library helps you find the right plugin for your needs.
Installing a plugin using a package manager like
npm does not enable it in your Gatsby site. To finish adding a plugin, make sure your
gatsby-config.js file has a
plugins array so you can include a space for the plugins needed to build your site:
When adding multiple plugins, they should be separated by commas in the
If a plugin does not require any options, you can add its name as a string to the
Many plugins have optional or required options to configure them. Instead of adding a name string to the
plugins array, add an object with its name and options. Most plugins show examples in their
README file or page in the Gatsby plugin library.
Here’s an example showing how to write an object with keys to
resolve the plugin name and an
options object with any applicable settings:
You can add plugins with and without options in the same array. Your site’s config file could look like this:
There are several more configuration options available for
gatsby-config.js. You can find a list of every option in the Gatsby Configuration API page.