Another Gatsby cheat sheet
Tags: gatsby, react, javascript
Published: 2021-11-05 13:33:21

## Concepts

Gatsby is a phenomenal framework that abstracts cutting edge technologies.

{% details 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.
{% enddetails %}

{% details GraphQL %}
Gatsby uses [this query language](https://www.gatsbyjs.com/docs/conceptual/graphql-concepts/) to make data available in the browser when needed by your components.
{% enddetails %}

{% details Webpack %}
Gatsby uses [this JavaScript module bundler](https://www.gatbsyjs.com/docs/conceptual/gatsby-jargon/#webpack).
{% enddetails %}

{% details 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.
{% enddetails %}

{% details Plugins %}
[Node.js packages](https://www.gatbsyjs.com/docs/conceptual/gatsby-jargon/#plugins) that implement Gatsby APIs to add extra functionality to a Gatsby site.
{% enddetails %}

{% details Themes %}
Themes are a particular type of plugins with their own `gatsby-config.js`. 
{% enddetails %}

{% details Theme shadowing %}
You can override components, objects, and anything else in any theme’s src directory. You'll find [more details here](https://www.gatbsyjs.com/docs/conceptual/how-shadowing-works/).
{% enddetails %}

## v2 to v3

V3 is a major version that comes with breaking changes.

{% details Update Gatsby %}
    `yarn add gatsby@latest`
{% enddetails %}

{% details Update all other dependencies %}
    `yarn upgrade-interactive --latest`
{% enddetails %}

{% details The official guide %}
The Gatsby community is crazy good at writing documentation. You can [read the migration guide](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/)
{% enddetails %}

## Core files

{% details 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
{% enddetails %}

{% details 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).
{% enddetails %}

{% details 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](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-ssr/).
{% enddetails %}

{% details gatsby-browser.js %}
[Browser APIs](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-browser/) let you respond to Gatsby-specific events within the browser. This is where you can interact with the client side.
{% enddetails %}

## Plugins

Gatsby has a strong ecosystem with [helpful plugins](https://www.gatsbyjs.com/plugins). 

{% details Adding a plugin %}
Install the node package and open the `gatsby-config.js` file:

```javascript
module.exports = {
  siteMetadata: {},
  plugins: ["gatsby-plugin-image"],
}
```
_Note that you can have additional lines for the plugin configuration_
{% enddetails %}

{% details Must-have plugins %}
*   [Gatsby plugin manifest](https://www.gatsbyjs.com/plugins/gatsby-plugin-manifest/)
*   [Gatsby plugin offline](https://www.gatsbyjs.com/plugins/gatsby-plugin-offline/)
*   [Gatsby plugin image](https://www.gatsbyjs.com/plugins/gatsby-plugin-image/)
*   [Gatsby plugin react helmet](https://www.gatsbyjs.com/plugins/gatsby-plugin-react-helmet/)
*   [Gatsby source filesystem](https://www.gatsbyjs.com/plugins/gatsby-source-filesystem/)
*   [Gatsby plugin sass](https://www.gatsbyjs.com/plugins/gatsby-plugin-sass/)

There's a plugin for Google Analytics if you need too.
{% enddetails %}

{% details Best plugins for alternative approaches %}
    Use this list with caution and check the compatibility with the v3 before.
*   [Gatsby plugin preact](https://www.gatsbyjs.com/plugins/gatsby-plugin-preact/)
*   [Gatsby plugin purge css](https://www.gatsbyjs.com/plugins/gatsby-plugin-purgecss/)
*   [Gatsby plugin no javascript](https://www.gatsbyjs.com/plugins/gatsby-plugin-no-javascript/)
{% enddetails %}

## CLI

{% details Create the next big thing with Gatsby %}
    Start with `gatsby new the-next-big-thing`
{% enddetails %}

{% details Start a new dev server %}
    Run `gatsby develop -o`, the `-o` option opens the site in the browser as a new tab.
{% enddetails %}

{% details Delete the cache and the public folder %}
    Run `gatsby clean`.
{% enddetails %}

{% details Build the site %}
    Run `gatsby build`.
{% enddetails %}

{% details Serve the build %}
    Run `gatsby serve -o`, the `-o` option opens the site in the browser as a new tab.
{% enddetails %}

{% details Test the site locally on a real mobile phone %}
    Run `gatsby develop -H 0.0.0.0 -p 8000`
{% enddetails %}

## Flags

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

```js
// In your gatsby-config.js
module.exports = {
  flags: {
    FAST_DEV: true,
  },
}
```

{% details PRESERVE_WEBPACK_CACHE %}
    to keep webpack’s cache when changing `gatsby-node.js` & `gatsby-config.js` files because you rarely need to delete it
{% enddetails %}

{% details FAST_DEV %} 
    to improve dev server start time
{% enddetails %}

{% details DEV_SSR %} 
    to detect SSR bugs and fix them without having to build
{% enddetails %}

{% details QUERY_ON_DEMAND %}
    to only run queries when needed instead of running all queries upfront
{% enddetails %}

{% details LAZY_IMAGES %}
    to skip process images during development until there’s an explicit request for them from the browser
{% enddetails %}

{% details 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
{% enddetails %}

{% details FAST_REFRESH %}
    to use React Fast Refresh instead of the legacy react-hot-loader for instantaneous feedback
{% enddetails %}

{% details PARALLEL_SOURCING %}
    to run all source plugins at the same time instead of serially
{% enddetails %}

{% details FUNCTIONS %} 
    Serverless functions for Gatsby cloud
{% enddetails %}

## Source from CMS

Gastby can source from various CMS and APIs.

### WordPress

Gatsby can connect to WordPress through GraphQL to query contents.

See [Gatsby demo v3 - WordPress](https://github.com/jmau111/demo-gatsby-v3-wordpress). Read the installation guide carefully.