My Gatsby v3 cheat sheet

Be aware it's not an exhaustive list.

Permalink to heading Concepts Concepts

Gatsby is a phenomenal framework that abstracts cutting edge technologies.

React hydration Gatsby uses React DOM server-side APIs to generate static HTML contents and those pages eventually get rehydrated into a React application. Some of the same JavaScript code used to generate Gatsby pages is reused in the browser where DOM APIs like window are available.
GraphQL Gatsby uses this query language to make data available in the browser when needed by your components.
Webpack Gatsby uses this JavaScript module bundler.
Routing The mechanism for loading the correct content in a website or app based on a network request - usually a URL. Gatsby creates paths to access content and handles dynamic routing with content prefetching under the hood.
Plugins Node.js packages that implement Gatsby APIs to add extra functionality to a Gatsby site.
Themes Themes are a particular type of plugins with their own gatsby-config.js.
Theme shadowing You can override components, objects, and anything else in any theme’s src directory. You'll find more details here.

Permalink to heading v2 to v3 v2 to v3

V3 is a major version that comes with breaking changes.

Update Gatsby yarn add gatsby@latest
Update all other dependencies yarn upgrade-interactive --latest
The official guide The Gatsby community is crazy good at writing documentation. You can read the migration guide

Permalink to heading Core files Core files

gatsby-config.js The main configuration file that contains:
  • the list of plugins and themes (NPM packages, local plugins, etc)
  • the siteMetadata object
  • some mappings
gatsby-node.js Gatsby loads that file after the plugins, the cache, the bootstrap, and the GraphQL scheme. You get access to the CreatePages API to add your custom nodes (~ URLs).
gatsby-ssr.js That file controls a special step, when Gatsby handles by itself the equivalent of a node server (~ compilation) to transform React code into static HTML assets. You get access to SSR APIs.
gatsby-browser.js Browser APIs let you respond to Gatsby-specific events within the browser. This is where you can interact with the client side.

Permalink to heading Plugins Plugins

Gatsby has a strong ecosystem with helpful plugins.

Adding a plugin Install the node package and open the gatsby-config.js file:
module.exports = {
  siteMetadata: {},
  plugins: ["gatsby-plugin-image"],
}
Note that you can have additional lines for the plugin configuration
Must-have plugins

There's a plugin for Google Analytics if you need too.

Best plugins for alternative approaches Use this list with caution and check the compatibility with the v3 before.

Permalink to heading CLI CLI

Create the next big thing with Gatsby Start with gatsby new the-next-big-thing
Start a new dev server Run gatsby develop -o, the -o option opens the site in the browser as a new tab.
Delete the cache and the public folder Run gatsby clean.
Build the site Run gatsby build.
Serve the build Run gatsby serve -o, the -o option opens the site in the browser as a new tab.
Test the site locally on a real mobile phone Run gatsby develop -H 0.0.0.0 -p 8000

Permalink to heading Flags Flags

You can add flags in your config to customize your dev experience:

// In your gatsby-config.js
module.exports = {
  flags: {
    FAST_DEV: true,
  },
}
PRESERVE_WEBPACK_CACHE to keep webpack’s cache when changing gatsby-node.js & gatsby-config.js files because you rarely need to delete it
FAST_DEV to improve dev server start time
DEV_SSR to detect SSR bugs and fix them without having to build
QUERY_ON_DEMAND to only run queries when needed instead of running all queries upfront
LAZY_IMAGES to skip process images during development until there’s an explicit request for them from the browser
PRESERVE_FILE_DOWNLOAD_CACHE to keep the downloaded files cache when changing gatsby-node.js & gatsby-config.js files because, again, you rarely need to re-download them
FAST_REFRESH to use React Fast Refresh instead of the legacy react-hot-loader for instantaneous feedback
PARALLEL_SOURCING to run all source plugins at the same time instead of serially
FUNCTIONS Serverless functions for Gatsby cloud

Permalink to heading Source from CMS Source from CMS

Gastby can source from various CMS and APIs.

  2. All cheat sheets
  3. My Gatsby v3 cheat sheet
This content is available in other languages: