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 owngatsby-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 guidePermalink 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 theCreatePages
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 thegatsby-config.js
file:module.exports = {
siteMetadata: {},
plugins: ["gatsby-plugin-image"],
}
Must-have plugins
- Gatsby plugin manifest
- Gatsby plugin offline
- Gatsby plugin image
- Gatsby plugin react helmet
- Gatsby source filesystem
- Gatsby plugin sass
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 withgatsby new the-next-big-thing
Start a new dev server
Rungatsby develop -o
, the -o
option opens the site in the browser as a new tab.Delete the cache and the public folder
Rungatsby clean
.Build the site
Rungatsby build
.Serve the build
Rungatsby serve -o
, the -o
option opens the site in the browser as a new tab.Test the site locally on a real mobile phone
Rungatsby 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 changinggatsby-node.js
& gatsby-config.js
files because you rarely need to delete itFAST_DEV
to improve dev server start timeDEV_SSR
to detect SSR bugs and fix them without having to buildQUERY_ON_DEMAND
to only run queries when needed instead of running all queries upfrontLAZY_IMAGES
to skip process images during development until there’s an explicit request for them from the browserPRESERVE_FILE_DOWNLOAD_CACHE
to keep the downloaded files cache when changinggatsby-node.js
& gatsby-config.js
files because, again, you rarely need to re-download themFAST_REFRESH
to use React Fast Refresh instead of the legacy react-hot-loader for instantaneous feedbackPARALLEL_SOURCING
to run all source plugins at the same time instead of seriallyFUNCTIONS
Serverless functions for Gatsby cloudPermalink to heading Source from CMS Source from CMS
Gastby can source from various CMS and APIs.
This content is available in other languages: