Frameworks /Framework support /

Gatsby on Netlify

Gatsby is a React-based, open source static site generator that pulls in data using a GraphQL API layer that can connect to a wide array of content sources.

# Key features

These Gatsby features provide key benefits for sites and apps, including ones built and deployed with Netlify.

  • Content aggregation. Gatsby provides a diverse ecosystem of data plugins that allow developers to use a centralized GraphQL API to pull in content from files, APIs, and SaaS platforms. This makes development feel familiar, even if content sources are completely different.

  • Performance optimizations. By default, Gatsby optimizes JavaScript bundles, adds preloading and browser optimizations, and includes other performance enhancements. In general, Gatsby sites are performant and fast.

  • Image optimization. Gatsby ships an image component that works with the GraphQL data layer to generate highly optimized images. The images are lazy-loaded and configured for different viewport sizes. This cuts down on page load times and bandwidth usage. You can also use Netlify Image CDN with Gatsby for deferred image resizing instead of processing images at build time.

  • Serverless functions. Gatsby includes an integrated Functions feature to help create an API for a site or application.

  • Server-side rendering (SSR) and deferred static generation (DSG). You can choose between several rendering modes, including SSR and DSG. This means you can pick the rendering mode that makes sense for your site.

# Netlify integration

Choose your Gatsby version:

When you trigger a build on Netlify for a site that uses Gatsby version 5.12.0 or later, Gatsby detects that you are using Netlify and automatically installs gatsby-adapter-netlify. This is a Gatsby adapter that enables zero-configuration deployments, making it easier to build and deploy your Gatsby sites. The same automatic detection and installation occurs when you trigger a build using the Netlify CLI.

You can also choose to install the adapter yourself.

Note that if your site already uses the Gatsby adapter for Netlify, you don’t have to use the Essential Gatsby build plugin.

Gatsby 5 requires updated Node.js version

Gatsby 5 requires Node.js 18. If your build is using another Node.js version, follow our Node.js docs to manually set the Node.js version to 18.

# Gatsby adapter for Netlify

The official Gatsby adapter for Netlify, gatsby-adapter-netlify, enables zero-configuration deployments for your site. When you trigger a build on Netlify for a site that uses Gatsby version 5.12.0 or later, Gatsby automatically installs the adapter. The adapter prepares your site for deployment on Netlify in a number of ways, including:

  • Applying HTTP headers to assets
  • Applying redirects and rewrites
  • Applying trailing slash behavior to URLs
  • Setting up user-defined API functions to be used on Netlify
  • Setting up Deferred Static Generation (DSG) and Server-Side Rendering (SSR)
  • Storing Gatsby cache after build is complete and restoring it on subsequent builds to decrease build time between builds

For more information on adapters, including information on how to create your own, visit Gatsby’s documentation on adapters.

# Install the Gatsby adapter for Netlify

Gatsby will automatically install gatsby-adapter-netlify for new Gatsby sites on Netlify. If you want to install the adapter manually, you can use the use the following command:

  npm install gatsby-adapter-netlify

If you want to further configure the adapter, you can add gatsby-adapter-netlify to your gatsby-config.js file and configure the adapter option. For example:

  const adapter = require("gatsby-adapter-netlify")

  module.exports = {
    adapter: adapter({
      excludeDatastoreFromEngineFunction: false,

For more information, visit the gatsby-adapter-netlify docs.

# Limitations

StaticImage and gatsby-transformer-sharp don’t work properly for SSR or DSG pages. Instead, you can host your images on a CDN such as Cloudinary or imgix.

# Auto-generated Netlify Functions

To support Gatsby Functions and SSR/DSG render modes, the Gatsby adapter automatically generates Netlify Functions called SSR and DSG. If your site doesn’t have Gatsby Functions or SSR/DSG pages, then the Netlify Functions won’t be generated.

# Optional loading of the Gatsby datastore from the CDN

By default, Netlify includes the Gatsby datastore in the Netlify Function bundle, which is a deployment package that’s zipped for direct upload to AWS. If you have a larger site, the site’s datastore may exceed the maximum function deploy size, preventing you from successfully deploying your website.

GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE is an environment variable that loads the Gatsby datastore from the CDN rather than bundling it with the function, bypassing the size limitation.

Note that enabling loading the datastore from the CDN results in different page load behavior. On the first load of functions that handle SSR and DSG pages, the datastore is downloaded, which can result in a slower initial page load.

During the build process, pre-warm requests are sent to the SSR and DSG function endpoints to reduce the user-facing impact of the datastore download.

# Local development

When developing Gatsby Functions, you can use the built-in gatsby develop functions server. However, if you want to run the Netlify Functions that are generated during the build step, you can use netlify dev. Make sure to run netlify build first to generate the Netlify Functions from your Gatsby Functions.

# Suggested configuration values

When you link a repository for a Gatsby project, Netlify provides a suggested build command and publish directory: gatsby build and public.

If you’re using the CLI to run Netlify Dev for a local development environment, Netlify suggests a dev command and port: gatsby develop and 8000.

You can override suggested values or set them in a configuration file instead, but suggested values from automatic framework detection may help simplify the process of setting up a Gatsby site on Netlify.

For manual configuration, check out the typical build settings for Gatsby.

# Environment variables

Environment variables prefixed with GATSBY_ are processed by Gatsby and made available in the browser for client-side JavaScript access. For more information on how to use environment variables in Gatsby, including with SSR or DSG pages, check out the Environment variables and frameworks doc.

# Netlify Image CDN

Not supported for Gatsby 5.12

If your site uses Gatsby version 5.12.x with a Gatsby adapter, deferred image resizing with a CDN is not supported. Upgrade to Gatsby 5.13.0 or later to use this feature.

Gatsby supports deferred image resizing with Netlify Image CDN.

To enable the image CDN, you need to do the following:

  • Set the environment variable NETLIFY_IMAGE_CDN to true
  • Use the Contentful, Drupal, or WordPress source plugins

For more information, including how to allow remote images, visit the Gatsby adapter for Netlify README.

# More resources