Gatsby on Netlify

Last updated: September 8, 2023

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 the Gatsby Image CDN on Netlify.
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

When you trigger a build for a Gatsby project using Gatsby version 5.12.0 or later, Gatsby will detect that you are using Netlify and will automatically install gatsby-adapter-netlify. This is a Gatsby adapter that enables zero-configuration deployments, making it easier to build and deploy your Gatsby sites. 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 a site using 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.

When you link a repository for a project, Netlify detects the framework your site is using. If you are using Gatsby version 5.11.0 or earlier, Netlify will automatically install the Essential Gatsby build plugin and provides suggested configuration values. For existing sites already linked to Netlify, you can choose to install the plugin yourself.

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.

# Essential Gatsby build plugin

The Essential Gatsby build plugin enables key functionality on sites that use Gatsby versions earlier than 5.12.0. It speeds up Netlify builds by preserving a site’s public and .cache directories between builds. The plugin supports Gatsby Functions and SSR and DSG rendering. If you don’t need those, you can remove the plugin from your site.

Gatsby sites on Netlify need two plugins to support all features:

The Essential Gatsby build plugin (@netlify/plugin-gatsby). This plugin installs automatically for all Gatsby sites deployed on Netlify.
The Gatsby plugin for Netlify (gatsby-plugin-netlify). This needs to be installed manually and is required for SSR rendering, Gatsby redirects, and asset caching rules.

# Install the Essential Gatsby build plugin

New Gatsby sites on Netlify automatically install the Essential Gatsby build plugin. You can confirm this in the build logs. If you want to install it manually, you can use file-based plugin installation and add the plugin as @netlify/plugin-gatsby in your netlify.toml file.

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

# Install the Gatsby plugin for Netlify

To enable SSR rendering, Gatsby redirects, and asset caching rules, you must also install the Gatsby plugin gatsby-plugin-netlify.

To install the Gatsby plugin for Netlify, follow the Gatsby plugin process:

Add the package as a dependency.
```
npm install -D gatsby-plugin-netlify
```
Add gatsby-plugin-netlify to your gatsby-config.js file’s plugins array.
```
module.exports = {
  plugins: ["gatsby-plugin-netlify"],
}
```

For more information, including optional plugin configuration, check out the gatsby-plugin-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 Essential Gatsby build plugin automatically generates Netlify Functions called __api, __ssr, __dsg, and __ipx. If your site doesn’t have Gatsby Functions or SSR/DSG pages, then the Netlify Functions won’t be generated.

You can use one or more of the following build environment variables to directly control generation of these functions.

NETLIFY_SKIP_GATSBY_FUNCTIONS: skips generation of all functions (__api, __ssr, __dsg, and __ipx). Takes precedence over the following function skip environment variables.
NETLIFY_SKIP_API_FUNCTION: skips generation of the __api function.
NETLIFY_SKIP_SSR_FUNCTION: skips generation of the __ssr function.
NETLIFY_SKIP_DSG_FUNCTION: skips generation of the __dsg function.

# 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.

# Gatsby Image CDN on Netlify

Not supported for Gatsby adapters

If your site uses Gatsby version 5.12.0 or later with Gatsby adapters, deferred image resizing with a CDN is not supported.

The prerelease version of Gatsby includes beta support for deferred image resizing with a CDN.

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

Set the environment variable GATSBY_CLOUD_IMAGE_CDN to true
Use the beta version of Gatsby
Use the Contentful or WordPress source plugins

Check out the full details in the Essential Gatsby build plugin’s documentation.

# More resources

Did you find this doc useful?

Your feedback helps us improve our docs.