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 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 link a repository for a project, Netlify detects the framework your site is using. If your site is built with Gatsby, Netlify automatically installs 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, which isn’t the default version of Node.js on our build image. To use Gatsby 5 on Netlify, follow our Node.js docs to set the Node.js version for your build to 18. We also recommend setting the Node.js version for the Netlify Functions runtime to nodejs18.x to maintain consistency between the versions used for builds and functions. Follow our Node.js version for runtime docs for details.

# Essential Gatsby build plugin

The Essential Gatsby build plugin enables key functionality on your Gatsby site. 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.

Redirects in netlify.toml are not supported. Use a _redirects file or Gatsby redirects instead. Visit the gatsby-plugin-netlify docs to learn more about working with redirects.

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

The Essential Gatsby plugin reduces the user-facing impact the datastore download has by sending pre-warm requests to the SSR and DSG function endpoints as part of the build process.

# 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 the Essential Gatsby build plugin generates, 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

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.