Netlify.com Homepage Netlify Docs

Contact

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.

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

# Netlify integration

When you link a repository for a project, Netlify tries to detect the framework your site is using. If your site is built with Gatsby, Netlify automatically installs the Essential Gatsby build plugin version 1.0 and provides suggested configuration values. For existing sites already linked to Netlify, you can choose to install the plugin yourself.

# Essential Gatsby build plugin

The Essential Gatsby build plugin version 1.0 enables key functionality on your site for Gatsby 3 and earlier. It speeds up Netlify builds for Gatsby sites by preserving a site’s public and .cache directories between builds. The plugin also adds support for Gatsby Functions created on your site. If you don’t need those things, you can remove the plugin from your site.

Gatsby 4 beta on Netlify

Gatsby 4 will introduce additional rendering options: server-side rendering (SSR) and deferred static generation (DSG). To use Gatsby 4 beta on Netlify, your site needs the following:

  • the Essential Gatsby build plugin version 2.0 beta, an official Netlify plugin for Gatsby
  • gatsby-plugin-netlify version 4 beta, an official Gatsby plugin for Netlify that automatically generates redirects for Gatsby 4 sites that use SSR

Check out the Essential Gatsby README for required manual installation and configuration steps during the beta period.

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

Gatsby environment variables

Any environment variables prefixed with GATSBY_ are processed by Gatsby and made available in the browser for client-side JavaScript access. Visit the Gatsby docs about environment variables for more information.

# More resources