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 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 yourgatsby-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.
# Netlify Image CDN
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
totrue
- Use the Contentful, Drupal, or WordPress source plugins
For more information, including how to allow remote images, visit the Essential Gatsby build plugin’s documentation.
# More resources
- Typical Gatsby build settings
- Gatsby Adapters: Realize the Full Potential of Gatsby on Your Platform
- Essential Gatsby build plugin documentation
- Five Optimizations for Faster Gatsby Builds
- Gatsby 101: Features, Benefits, and Trade-Offs
- Improve Gatsby Build Speeds With Parallel Image Processing
- Netlify Blog: Gatsby posts
- Deploying to Netlify
- Gatsby documentation
Did you find this doc useful?
Your feedback helps us improve our docs.