Beginner8 minutesUpdated 2026-03-01

Gatsby is a React-based static site generator with a rich plugin ecosystem. Netlify and Gatsby have a long history together — Netlify was one of the earliest champions of Gatsby, and the integration is mature and well-tested. With gatsby-plugin-netlify, you get optimized headers, redirects, and caching out of the box.

Prerequisites

Node.js 18 or later installed
A Gatsby project
A Netlify account
Git repository (GitHub, GitLab, or Bitbucket)

Step 1: Install the Netlify plugin

Add gatsby-plugin-netlify to your project. This plugin generates optimal HTTP headers, handles redirects, and enables caching for your Gatsby site on Netlify.

npm install gatsby-plugin-netlify

Step 2: Add the plugin to your Gatsby config

Add gatsby-plugin-netlify to your gatsby-config.js plugins array. It should be the last plugin in the list.

gatsby-config.js

module.exports = {
  plugins: [
    // ... your other plugins
    'gatsby-plugin-netlify',
  ],
}

The plugin must be last in the plugins array so it can process the output of all other plugins.

Step 3: Push to Git and connect to Netlify

Push your code to a Git provider and import the project in Netlify. Netlify auto-detects Gatsby and configures the build settings.

Build settings

Build command: gatsby build
Publish directory: public

Step 4: Configure environment variables

Add API keys and other secrets in Netlify's dashboard. Gatsby accesses these during the build process. Variables prefixed with GATSBY_ are available in client-side code.

GATSBY_API_URL=https://api.example.com
CMS_ACCESS_TOKEN=your-secret-token

Step 5: Deploy and verify

Click 'Deploy site'. Gatsby builds can take longer than other frameworks due to image processing and GraphQL data fetching. Subsequent builds are faster thanks to Gatsby's and Netlify's build caches.

If your Gatsby build is slow, check if you're processing many images. Consider using gatsby-plugin-image with lazy loading to reduce build times.

netlify.toml Configuration

This configures Netlify to build your Gatsby site and publish the 'public' output directory. The gatsby-plugin-netlify package handles headers and redirects automatically.

netlify.toml

[build]
  command = "gatsby build"
  publish = "public"

[[plugins]]
  package = "gatsby-plugin-netlify"

Common Errors

ENOMEM: not enough memory

Cause: Gatsby's build process is memory-intensive, especially with many images or pages. Netlify's build environment has limited memory.

Fix: Set the NODE_OPTIONS environment variable to '--max_old_space_size=4096' in Netlify's environment variables. For very large sites, consider Netlify's High-Performance Build tier.

Error: Cannot query field on type

Cause: A GraphQL query references a field that doesn't exist, often due to missing source plugins or changed data structure.

Fix: Run 'gatsby clean' locally, then rebuild. Check that all source plugins are properly configured and that your CMS data structure matches your queries.

Build exceeded maximum allowed runtime

Cause: Gatsby sites with many pages or heavy image processing can exceed Netlify's build timeout.

Fix: Enable Gatsby's incremental builds with the GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true environment variable. This rebuilds only changed pages.

Pro Tips

Enable Gatsby Cloud-style incremental builds on Netlify by using the Gatsby cache plugin and persistent build cache.

Use Netlify's split testing feature to A/B test different versions of your Gatsby site.

Set up Netlify's build hooks to trigger a rebuild when your CMS content changes.

Monitor your Gatsby build times in the Netli.fyi app — track build performance over time.

Use Netlify's branch deploys to test Gatsby upgrades on a separate branch before merging to production.

Deploy Gatsby to Netlify