.circleci/config.yml

@@ -10,11 +10,15 @@ executors:
         default: "14.17.0"
     docker:
       - image: cimg/node:<< parameters.image >>
+    environment:
+      GATSBY_CPU_COUNT: 2
 
 aliases:
   e2e-executor: &e2e-executor
     docker:
       - image: cypress/browsers:node14.15.0-chrome86-ff82
+    environment:
+      GATSBY_CPU_COUNT: 2
 
   restore_cache: &restore_cache
     restore_cache:

README.md

@@ -4,19 +4,19 @@
   </a>
 </p>
 <h1 align="center">
-  Gatsby v3
+  Gatsby v4
 </h1>
 
 <p align="center">
   ⚛️ 📄 🚀
 </p>
 <p align="center">
   <strong>
-    Fast in every way that matters
+    Static. That. Scales.
   </strong>
 </p>
 <p align="center">
-  Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps
+  Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps. </br> It combines the control and scalability of dynamically rendered sites with the speed of static-site generation, creating a whole new web of possibilities.
 </p>
 <p align="center">
   <a href="https://github.com/gatsbyjs/gatsby/blob/master/LICENSE">
@@ -66,6 +66,8 @@ Gatsby is a modern web framework for blazing fast websites.
   limitations. Gatsby sites are fully functional React apps, so you can create high-quality,
   dynamic web apps, from blogs to e-commerce sites to user dashboards.
 
+- **Choose your Rendering Option.** You can choose alternative [rendering options](https://gatsbyjs.com/docs/conceptual/rendering-options/), namely Deferred Static Generation (DSG) and Server-Side Rendering (SSR), in addition to Static Site Generation (SSG) — on a per-page basis. This type of granular control allows you to optimize for performance and productivity without sacrificing one for the other.
+
 - **Use a Modern Stack for Every Site.** No matter where the data comes from, Gatsby sites are
   built using React and GraphQL. Build a uniform workflow for you and your team, regardless of
   whether the data is coming from the same backend.
@@ -88,6 +90,7 @@ Gatsby is a modern web framework for blazing fast websites.
 
 - [Get Up and Running in 5 Minutes](#-get-up-and-running-in-5-minutes)
 - [Learning Gatsby](#-learning-gatsby)
+- [Release Notes](#-release-notes)
 - [Migration Guides](#-migration-guides)
 - [How to Contribute](#-how-to-contribute)
 - [License](#-license)
@@ -146,28 +149,28 @@ Wondering what we've shipped recently? Check out our [release notes](https://www
 
 ## 💼 Migration Guides
 
-Already have a Gatsby site? These handy guides will help you add the improvements of Gatsby v3 to your site without starting from scratch!
+Already have a Gatsby site? These handy guides will help you add the improvements of Gatsby v4 to your site without starting from scratch!
 
+- [Migrate from v3 to v4](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
 - [Migrate from v2 to v3](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/)
-- [Migrate from v1 to v2](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v1-to-v2/)
 
 ## ❗ Code of Conduct
 
 Gatsby is dedicated to building a welcoming, diverse, safe community. We expect everyone participating in the Gatsby community to abide by our [**Code of Conduct**](https://www.gatsbyjs.com/contributing/code-of-conduct/). Please read it. Please follow it. In the Gatsby community, we work hard to build each other up and create amazing things together. 💪💜
 
 ## 🤝 How to Contribute
 
-Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Gatsby community! :muscle::purple_heart:
+Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Gatsby community!
 
 Check out our [**Contributing Guide**](https://www.gatsbyjs.com/contributing/how-to-contribute/) for ideas on contributing and setup steps for getting our repositories up and running on your local machine.
 
 ### A note on how this repository is organized
 
 This repository is a [monorepo](https://trunkbaseddevelopment.com/monorepos/) managed using [Lerna](https://github.com/lerna/lerna). This means there are [multiple packages](https://github.com/gatsbyjs/gatsby/tree/master/packages) managed in this codebase, even though we publish them to NPM as separate packages.
 
-### Contributing to Gatsby v2
+### Contributing to Gatsby v3
 
-We are only accepting critical security patches for Gatsby v2.
+We are only accepting critical security patches for Gatsby v3.
 
 ## 📝 License
 

docs/contributing/docs-contributions/index.md

@@ -14,7 +14,7 @@ Check the GitHub repo for issues labeled with ["type: documentation" and "good f
 
 ## Options for contributing to the Gatsby docs
 
-When working on the Gatsby.js documentation, you can choose between two major styles of working:
+When working on the Gatsby documentation, you can choose between two major styles of working:
 
 - [Work directly in the GitHub UI](#modifying-markdown-files), using the "Edit this File" and commit capabilities without having to clone the repository. This is useful for quick documentation updates, typo fixes, and lightweight Markdown changes.
 - Clone the Gatsby.js repo and make changes to the Markdown files using your favorite text editor. Currently (as of March 2021), there is no way for community members to build the docs site locally. We are working internally to figure out a fix for this.

docs/contributing/how-to-file-an-issue.md

@@ -2,21 +2,16 @@
 title: How to File an Issue
 ---
 
-The Gatsby GitHub [issue tracker](https://github.com/gatsbyjs/gatsby/issues) is the preferred channel for bug reports, documentation, feature requests and [submitting pull requests](/contributing/how-to-open-a-pull-request/).
+The Gatsby GitHub [issue tracker](https://github.com/gatsbyjs/gatsby/issues) is the preferred channel for bug reports, documentation requests, and [submitting pull requests](/contributing/how-to-open-a-pull-request/).
 
 To resolve your issue, please select the appropriate category:
 
-- Bug Reports
+- Bug Report
 - Documentation
-- Feature Requests
-- New [Translation](/contributing/translation#creating-a-new-translation) Requests
 
 For bug reports, include in your issue:
 
-- Gatsby version, Node.js version, OS version
-- The contents of your `gatsby-config.js` and `package.json` as well as your
-  `gatsby-node.js`, `gatsby-browser.js`, and `gatsby-ssr.js` files depending on
-  changes you've made there.
+- Follow the issue template prompting you for each entry
 - A [reproduction](/contributing/how-to-make-a-reproducible-test-case/) for debugging and taking action
 
 Please do not use the issue tracker for personal support requests. [Stack Overflow](https://stackoverflow.com/questions/ask?tags=gatsby) (**gatsby** tag) and the [Gatsby Discord](https://gatsby.dev/discord) are better places to get help.

docs/contributing/how-to-make-a-reproducible-test-case.md

@@ -16,14 +16,14 @@ A reproducible test case is a great way to share a specific environment that cau
 
 ## Steps to create a reproducible test case
 
-- Create a new Gatsby site with a starter, the official `hello-world` starter is a great 'barebones' starting point here: `gatsby new bug-repro https://github.com/gatsbyjs/gatsby-starter-hello-world`
+- Create a new Gatsby site with a starter, the official `gatsby-starter-minimal` starter is a great 'barebones' starting point here: `gatsby new bug-repro https://github.com/gatsbyjs/gatsby-starter-minimal`
 - Add any Gatsby plugins that relate to the issue. For example, if you're having problems with Gatsby MDX you should install and configure [`gatsby-plugin-mdx`](/plugins/gatsby-plugin-mdx/). Only add plugins that are needed to demonstrate the problem.
 - Add the code needed to recreate the error you've seen.
 - Publish the code (your GitHub account is a good place to do this) and then link to it when [creating an issue](/contributing/how-to-file-an-issue/).
 
 ## Places to develop a reproducible test case
 
-- Locally with a starter: You can start with a [Starter](/docs/starters) locally and then build it on your own machine. Gatsby's official [`hello-world`](https://github.com/gatsbyjs/gatsby/tree/master/starters/hello-world) or [`default`](https://github.com/gatsbyjs/gatsby-starter-default) starter are both good foundations for a reproducible test case.
+- Locally with a starter: You can start with a starter locally and then build it on your own machine. Gatsby's official [`gatsby-starter-minimal`](https://github.com/gatsbyjs/gatsby-starter-minimal) is a good foundation for a reproducible test case.
 - Host on CodeSandbox: You can develop a Gatsby site straight from your browser with CodeSandbox using their [Gatsby template](https://codesandbox.io/s/github/gatsbyjs/gatsby-starter-default). CodeSandbox also hosts your site automatically, which can be useful to demonstrate the behavior of your site.
 
 ## Benefits of reproducible test cases

docs/contributing/how-to-open-a-pull-request.md

@@ -79,7 +79,7 @@ To test changes locally against the Gatsby [site and project files](https://gith
 
 ### Documentation PRs
 
-The Gatsby.js docs site mostly lives in the [www](https://github.com/gatsbyjs/gatsby/tree/master/www) and [docs](https://github.com/gatsbyjs/gatsby/tree/master/docs) directories on GitHub, including docs and tutorial content. There are also some [examples in the Gatsby repo](https://github.com/gatsbyjs/gatsby/tree/master/examples) referenced in the docs.
+The Gatsby docs site lives in [docs](https://github.com/gatsbyjs/gatsby/tree/master/docs) directories on GitHub, including docs and tutorial content. There are also some [examples in the Gatsby repo](https://github.com/gatsbyjs/gatsby/tree/master/examples) referenced in the docs.
 
 Additional docs PR steps:
 

docs/contributing/translation/sync-guide.md

@@ -169,7 +169,7 @@ If a page has significant changes, it may be worth splitting it into its own pul
 ```shell
 git checkout conflicts-9032a0
 git checkout -b sync-tutorial-0
-# Fix conflicts in /docs/docs/tutorial/part-zero/index.md
+# Fix conflicts in /docs/docs/tutorial/part-0/index.md
 git commit -am "Fix conflicts in tutorial part zero"
 git push -u origin sync-tutorial-0
 ```

docs/docs/add-a-service-worker.md

@@ -2,15 +2,15 @@
 title: Adding a Service Worker
 ---
 
-## What is a service worker
+## What is a service worker?
 
-A service worker is a script that your browser runs in the background, separate from a web page, opening the door to features that don't need a web page or user interaction. They increase your site availability in spotty connections, and are essential to making a nice user experience.
+A service worker is a script that your browser runs in the background, separate from a web page, opening the door to features that don't need a web page or user interaction. They increase your site availability in spotty connections and are essential to making a nice user experience.
 
 It supports features like push notifications and background sync.
 
 ## Using service workers in Gatsby with `gatsby-plugin-offline`
 
-Gatsby provides awesome plugin interface to create and load a service worker into your site [gatsby-plugin-offline](https://www.npmjs.com/package/gatsby-plugin-offline).
+Gatsby provides an awesome plugin interface to create and load a service worker into your site: [gatsby-plugin-offline](https://www.npmjs.com/package/gatsby-plugin-offline).
 
 You can use this plugin together with the [manifest plugin](https://www.npmjs.com/package/gatsby-plugin-manifest). (Don’t forget to list the offline plugin after the manifest plugin so that the manifest file can be included in the service worker).
 

docs/docs/adding-search-with-js-search.md

@@ -94,7 +94,7 @@ class Search extends Component {
     const { bookList } = this.state
     const dataToSearch = new JsSearch.Search("isbn")
     /**
-     *  defines a indexing strategy for the data
+     * defines an indexing strategy for the data
      * more about it in here https://github.com/bvaughn/js-search#configuring-the-index-strategy
      */
     dataToSearch.indexStrategy = new JsSearch.PrefixIndexStrategy()

docs/docs/adding-tags-and-categories-to-blog-posts.md

@@ -4,7 +4,7 @@ title: Creating Tags Pages for Blog Posts
 
 Creating tag pages for your blog post is a way to let visitors browse related content.
 
-To add tags to your blog posts, you will first want to have your site set up to turn your markdown pages into blog posts. To get your blog pages set up, see the [tutorial on Gatsby's data layer](/docs/tutorial/part-four/) and [Adding Markdown Pages](/docs/how-to/routing/adding-markdown-pages/).
+To add tags to your blog posts, you will first want to have your site set up to turn your markdown pages into blog posts. To get your blog pages set up, see the [tutorial on Gatsby's data layer](/docs/tutorial/part-4/) and [Adding Markdown Pages](/docs/how-to/routing/adding-markdown-pages/).
 
 The process will essentially look like this:
 

docs/docs/basic-hardware-software-requirements.md

@@ -18,7 +18,7 @@ This will be variable depending on the size of your site. Gatsby sites have been
 
 To develop with Gatsby, you'll need to install:
 
-- Node.js 10.13.0 (LTS) or higher
+- Node.js 14.15.0 (LTS) or higher
 - [npm](https://www.npmjs.com/) or [Yarn 1](https://classic.yarnpkg.com/lang/en/) package manager to install the [Gatsby CLI](/docs/reference/gatsby-cli/) and site dependencies.
   - npm is recommended for most developers.
   - Yarn is used for authoring Gatsby themes.

docs/docs/building-an-ecommerce-site-with-shopify.md

@@ -123,7 +123,7 @@ export const query = graphql`
 
 ## Generating a page for each product
 
-You can [programmatically create pages](/docs/tutorial/part-seven/) in Gatsby for every product in your Shopify store.
+You can [programmatically create pages](/docs/tutorial/part-7/) in Gatsby for every product in your Shopify store.
 
 Create a template for your product pages by adding a new file, `/src/templates/product.js`.
 

docs/docs/conceptual/building-with-components.md

@@ -79,7 +79,7 @@ pages are React components but very often these components are just wrappers aro
 `src/templates/post.js` is an example of a page component. It queries GraphQL
 for markdown data and then renders the page using this data.
 
-See [part seven](/docs/tutorial/part-seven/) of the tutorial for a detailed
+See [part seven](/docs/tutorial/part-7/) of the tutorial for a detailed
 introduction to programmatically creating pages.
 
 Example:

docs/docs/conceptual/data-fetching.md

@@ -25,7 +25,7 @@ Reasons to fetch certain data at build time vs. client runtime will vary, but in
 
 In order to fetch data at build time, you can use a source plugin or source data yourself. To source data yourself you can create an integration with a third-party system by creating [nodes for the GraphQL layer](/docs/node-creation/) in your `gatsby-node` file from retrieved data that becomes queryable in pages. This is the same method that source plugins implement to [source data](/docs/content-and-data/) while the site builds. You can read about that process in the [Creating a Source Plugin guide](/docs/how-to/plugins-and-themes/creating-a-source-plugin/).
 
-> This process of fetching data at build time and creating pages from the data is [covered in more depth in the tutorial](/docs/tutorial/part-five/) as well as the docs for [creating pages from data programmatically](/docs/programmatically-create-pages-from-data/).
+> This process of fetching data at build time and creating pages from the data is [covered in more depth in the tutorial](/docs/tutorial/part-5/) as well as the docs for [creating pages from data programmatically](/docs/programmatically-create-pages-from-data/).
 
 #### Source data to be queried at build time
 

docs/docs/conceptual/gatsby-jargon.md

@@ -60,7 +60,7 @@ GraphQL is a query language (the QL part of its name) that Gatsby uses to genera
 
 Using a special syntax, you describe the data you want in your component and then that data is given to you, such as site metadata from your `gatsby-config.js`, connected WordPress posts, Markdown files, images, and more. Gatsby uses GraphQL to enable components to declare the data they need and apply it to render on a page. Using GraphQL in Gatsby provides many [benefits](/docs/why-gatsby-uses-graphql/), such as the ability to return data from multiple sources in one query, and transform that data at the same time (such as using Gatsby Image).
 
-Here is how you get started using GraphQL in Gatsby: [Tutorial - Part 4](/docs/tutorial/part-four/)
+Here is how you get started using GraphQL in Gatsby: [Tutorial - Part 4](/docs/tutorial/part-4/)
 
 ## webpack
 

docs/docs/conceptual/graphql-concepts.md

@@ -118,7 +118,7 @@ When starting out with GraphQL, we recommend the following two tutorials:
 - https://www.howtographql.com/
 - https://graphql.org/learn/
 
-[The official Gatsby tutorial](/docs/tutorial/part-four/) also includes an introduction to using GraphQL specifically with Gatsby.
+[The official Gatsby tutorial](/docs/tutorial/part-4/) also includes an introduction to using GraphQL specifically with Gatsby.
 
 ## How do GraphQL and Gatsby work together?
 
@@ -194,20 +194,20 @@ markdownRemark {
 
 Gatsby has rich support for processing images. Responsive images are a big part of the modern web and typically involve creating 5+ sized thumbnails per photo. With Gatsby's [`gatsby-transformer-sharp`](/plugins/gatsby-transformer-sharp/), you can _query_ your images for responsive versions. The query automatically creates all the needed responsive thumbnails and returns `src` and `srcSet` fields to add to your image element.
 
-Combined with a special Gatsby image component, [gatsby-image](/plugins/gatsby-image/), you have a very powerful set of primitives for building sites with images.
+Combined with a special Gatsby image component, [gatsby-plugin-image](/plugins/gatsby-plugin-image/), you have a very powerful set of primitives for building sites with images.
 
-This is what a component using `gatsby-image` looks like:
+This is what a component using `gatsby-plugin-image` looks like:
 
 ```jsx
 import React from "react"
-import Img from "gatsby-image"
+import { GatsbyImage } from "gatsby-plugin-image"
 import { graphql } from "gatsby"
 
 export default function Page({ data }) {
   return (
     <div>
-      <h1>Hello gatsby-image</h1>
-      <Img fixed={data.file.childImageSharp.fixed} />
+      <h1>Hello gatsby-plugin-image</h1>
+      <GatsbyImage image={data.file.childImageSharp.gatsbyImageData} />
     </div>
   )
 }
@@ -218,9 +218,7 @@ export const query = graphql`
       childImageSharp {
         # Specify the image processing specifications right in the query.
         # Makes it trivial to update as your page's design changes.
-        fixed(width: 125, height: 125) {
-          ...GatsbyImageSharpFixed
-        }
+        gatsbyImageData(width: 125, height: 125, layout: FIXED)
       }
     }
   }

docs/docs/conceptual/plugins-themes-and-starters.md

@@ -102,7 +102,7 @@ Themes are intended to abstract several plugins into one, by making a `gatsby-co
 
 #### Custom components
 
-Custom components are most traditionally distributed as packages in the React ecosystem. Components don't need to hook into the Gatsby build system, so if shipped with a plugin they don't need to be included in a `gatsby-config`'s plugin array. This is the case with `gatsby-image` which is a React component. It doesn't need to be included in the plugins array because it is merely a component.
+Custom components are most traditionally distributed as packages in the React ecosystem. Components don't need to hook into the Gatsby build system, so if shipped with a plugin they don't need to be included in a `gatsby-config`'s plugin array.
 
 Some plugins ship with components you can use in a Gatsby site. An example is the [`<OutboundLink />` component from `gatsby-plugin-google-analytics`](/plugins/gatsby-plugin-google-analytics/?=#outboundlink-component). Other plugins, like [`gatsby-plugin-react-helmet`](/plugins/gatsby-plugin-react-helmet), require you to install components from other libraries.
 

docs/docs/conceptual/rendering-options.md

@@ -0,0 +1,97 @@
+---
+title: Rendering Options
+---
+
+import { Announcement } from "gatsby-interface"
+
+Gatsby is historically known as a static site generator enhanced with [React Hydration][1].
+But starting with Gatsby 4, you can choose alternative rendering options in addition to static site generation (SSG) — on a per-page basis.
+This type of granular control allows you to optimize for performance and productivity without sacrificing one for the other.
+
+## What is a rendering option?
+
+A rendering option defines the stage at which your page's user-facing HTML is generated. It can happen at build time
+(SSG or pre-rendering), during HTTP request (server-side rendering) or locally in the browser
+with Javascript (client-side rendering).
+
+<Announcement style={{marginBottom: "1.5rem"}}>
+
+For an in-depth explanation of each of those approaches and their trade-offs we
+highly recommend the ["Rendering on the Web"][3] article from the Chrome team.
+
+</Announcement>
+
+As already mentioned, Gatsby always supported SSG and [client-side rendering][4]. Now, two other rendering options are available: Deferred Static Generation (DSG) and Server-Side rendering (SSR).
+This guide dives into the what each of those modes means and when you might choose one over another.
+
+## Static Site Generation (SSG)
+
+SSG is the default rendering mode in Gatsby. While the name has the word "static" in it, it doesn't at all mean boring or lifeless. It simply means the entire site is pre-rendered into HTML, CSS, and JavaScript at build time, which then get served as static assets to the browser. Because all of that HTML, CSS, and JS is preprocessed and rendered at build time, Static Site Generation serves websites to users in the fastest possible way—your content is ready to go before the visitor even visits the site.
+
+How does SSG work?
+
+1. First, Gatsby generates all assets and HTML for all SSG pages at build time on a build server (this could be your laptop, any build service, or Gatsby Cloud worker if you use [Gatsby Cloud][6]).
+2. Then, the produced static files are uploaded to the content delivery network (CDN) provider of choice and served to end users. The build server is not needed after the build step and could even be turned off.
+
+This mode provides the most pleasant user experience, the highest level of security, and run-time scalability for your site.
+
+<Announcement style={{marginBottom: "1.5rem"}}>
+
+**Note:** SSG doesn't mean your site is not dynamic. You can still use JavaScript to communicate with any APIs,
+add private sections of your site for authorized users via [client-side rendering][4] and
+have any features that single-page applications (SPAs) can have.
+
+</Announcement>
+
+Here is how SSG works in Gatsby Cloud (although the principle remains the same with any build and CDN provider):
+
+![Diagram explaining SSG. On the first request of a visitor the HTML is served through a CDN cache to the user. On the second visit this also happens in the same way. The HTML is generated before publishing it to the CDN by a Gatsby Cloud worker.](../images/ssg-diagram.jpg)
+
+One downside of SSG is longer build times. As the number of pages of your site grows, so does the build time.
+Gatsby supports [incremental builds][5] to make sure the 2nd and subsequent builds only rebuild the parts of your site that changed,
+but for the initial build (the build without the cache), build times may become an issue. That's where
+Deferred Static Generation could be beneficial.
+
+## Deferred Static Generation (DSG)
+
+As the title suggests, Deferred Static Generation is conceptually very similar to SSG. The only difference with Deferred Static Generation is developers can choose to defer building certain pages until the first time a user requests it. Deferred Static Generation gives developers greater control over their site's build times.
+
+For example, imagine you have an archive of old articles that no longer receive significant traffic. There is
+no practical reason to generate them on each build (and thus delay the delivery of fresh articles). In this case, you may choose to defer the generation of old pages, and Gatsby will skip them during the build step.
+
+Subsequent requests to pages using DSG will hit the CDN cache the same way as with SSG.
+
+- [How-To Guide: Using Deferred Static Generation][7]
+
+![Diagram explaining DSG. On the first request of a visitor there's a cache miss and a Gatsby Cloud worker creates the requested page on the fly (through 3rdparty APIs and Gatsby DB). The visitor then will get the worker response while the generated file it uploaded to the CDN cache. On the second request the user will get the HTML from the CDN cache.](../images/dsg-diagram.jpg)
+
+Unlike SSG, Deferred Static Generation requires you to keep the build server running after the initial build (using the `gatsby serve` command).
+It implies a different deployment model and requires backend infrastructure. But don't worry: [Gatsby Cloud][6] supports it out-of-the-box.
+
+## Server-Side Rendering (SSR)
+
+SSG, DSG, and client-side rendering can handle a vast majority of use cases in web development. But there is a small niche when you may still need to generate HTML on-the-fly. That's when you'll need Server-Side Rendering.
+
+Server-Side Rendering is a method of content rendering in which each web page is served to a site visitor at runtime, meaning that a portion of the build process happens on each page request. Because the content is rendering during runtime, visitors will always get the latest version of content directly from the server—though they may have to wait a few seconds for it display.
+
+For example, imagine you are building a site with user reviews. You want those reviews to be immediately indexed by search engines as soon as they are posted, so client-side rendering is not an option.
+
+In this case, you may choose server-side rendering for pages with user reviews. Any time someone
+requests this page, Gatsby will call the `getServerData` function defined in the page component.
+That's where you can request any data from 3rd-party APIs. Gatsby passes the returned result as a `serverData`
+prop to your page component.
+
+You can also return HTTP headers along with data to control the page-caching strategy in your CDN.
+
+- [How to use server-side rendering][8]
+
+![Diagram explaining Server-Side rendering. Each request of a visitor is a cache miss and the necessary HTML/JSON is generated every time a request comes in.](../images/ssr-diagram.jpg)
+
+[1]: /docs/conceptual/react-hydration/
+[2]: /docs/adding-app-and-website-functionality/
+[3]: https://developers.google.com/web/updates/2019/02/rendering-on-the-web
+[4]: /docs/how-to/routing/client-only-routes-and-user-authentication
+[5]: /docs/reference/release-notes/v3.0#incremental-builds-in-oss
+[6]: /products/cloud/
+[7]: /docs/how-to/rendering-options/using-deferred-static-generation
+[8]: /docs/how-to/rendering-options/using-server-side-rendering

docs/docs/gatsby-internals-terminology.md

@@ -38,7 +38,7 @@ Contains a map of Page [path](#path) -> [Page object](#page-object).
 
 #### matchPath
 
-Think of this instead as `client matchPath`. It is ignored when creating pages during the build. But on the frontend, when resolving the page from the path ([find-path.js]()), it is used (via [reach router](https://github.com/reach/router/blob/master/src/lib/utils.js)) to find the matching page. Note that the [pages are sorted](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/internal-plugins/query-runner/pages-writer.js#L38) so that those with matchPaths are at the end, so that explicit paths are matched first.
+Think of this instead as `client matchPath`. It is ignored when creating pages during the build. But on the frontend, when resolving the page from the path ([find-path.js]()), it is used (via [reach router](https://github.com/reach/router/blob/master/src/lib/utils.js)) to find the matching page. Note that the [pages are sorted](https://github.com/gatsbyjs/gatsby/blob/7d6a0aa47b37f39aafd7c7b1debfe2cc88c5d540/packages/gatsby/src/bootstrap/requires-writer.ts#L154) so that those with matchPaths are at the end, so that explicit paths are matched first.
 
 This is also used by [gatsby-plugin-create-client-paths](/plugins/gatsby-plugin-create-client-paths/?=client). It duplicates pages whose path match some client-only prefix (e.g. `/app/`). The duplicated page has a `matchPath` so that it is resolved first on the frontend.
 

docs/docs/glossary/build.md

@@ -23,7 +23,7 @@ For smaller teams and projects, use `gatsby build`. The `gatsby build` command i
 npm install -g gatsby-cli
 ```
 
-Installing `gatsby-cli` globally makes Gatsby commands available system-wide. You'll use `gatsby new` to [create a new site](/docs/tutorial/part-zero/#create-a-gatsby-site), and `gatsby develop` to start a development server on your local machine.
+Installing `gatsby-cli` globally makes Gatsby commands available system-wide. You'll use `gatsby new` to [create a new site](/docs/tutorial/part-0/#create-a-gatsby-site), and `gatsby develop` to start a development server on your local machine.
 
 When you're ready to publish your project, run the `gatsby build` command to create a production-ready version of your site. Once built, you can use an SFTP client, the [rsync](https://en.wikipedia.org/wiki/Rsync) utility, or similar tool to transfer these files to your host.
 

docs/docs/glossary/headless-wordpress.md

@@ -7,7 +7,7 @@ Learn what headless WordPress means, how it differs from other ways of using Wor
 
 ### First, what is a Headless CMS?
 
-A [headless CMS](/docs/glossary/what-is-a-headless-cms) is a Content Management System that uses a decoupled architecture to allow it to act as a backend service accessed via an API or SDK. Traditionally, CMS have acted as both the frontend (presentation layer) and backend (content database) for content editing. With a headless implementation, the CMS only acts in the capacity of content editing and the frontend is served by another solution - like Gatsby.
+A [headless CMS](/docs/glossary/headless-cms/) is a Content Management System that uses a decoupled architecture to allow it to act as a backend service accessed via an API or SDK. Traditionally, CMS have acted as both the frontend (presentation layer) and backend (content database) for content editing. With a headless implementation, the CMS only acts in the capacity of content editing and the frontend is served by another solution - like Gatsby.
 
 ## Headless WordPress
 

docs/docs/glossary/node.md

@@ -17,7 +17,7 @@ A year later, Node.js made its debut as a standalone JavaScript runtime using th
 
 Once you've installed Node.js, you can use it to run JavaScript from the [command line](/docs/glossary#command-line). Type `node` at a prompt to launch the Node.js interactive shell. Include the path to a JavaScript file to execute that script: e.g. `node /Users/gatsbyfan/hello-world.js`.
 
-You will need to [install Node.js](/docs/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system) before using Gatsby. Gatsby is built using JavaScript, and requires the Node.js runtime.
+You will need to [install Node.js](/docs/tutorial/part-0/#install-nodejs-for-your-appropriate-operating-system) before using Gatsby. Gatsby is built using JavaScript, and requires the Node.js runtime.
 
 Installing Node.js also installs [npm](/docs/glossary#npm), the Node.js _package manager_. A package manager is specialized software that lets you install and update modules and packages used in your project.
 

docs/docs/glossary/npm.md

@@ -15,7 +15,7 @@ its plugins.
 
 npm is a [command line](/docs/glossary#command-line) tool. You'll need Terminal (Mac, Linux) or Command Prompt (Windows) in order to run its commands. To use one of npm's features, type `npm <command>`. For example, `npm help` displays a list of available features, including `install`, `uninstall`, `update`, and `search`.
 
-npm is installed alongside Node during the default [installation process](/docs/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system). You don't need to take any additional steps to add it to your environment.
+npm is installed alongside Node during the default [installation process](/docs/tutorial/part-0/#install-nodejs-for-your-appropriate-operating-system). You don't need to take any additional steps to add it to your environment.
 
 ### Using npm to install Gatsby
 
@@ -58,4 +58,4 @@ This will update the dependencies list of `package.json` and `package-lock.json`
 - [npm](https://www.npmjs.com/) official website
 - [Node.js](https://nodejs.org/en/) official website
 - [An introduction to the npm package manager](https://nodejs.dev/an-introduction-to-the-npm-package-manager) from Nodejs.dev
-- [Set Up Your Development Environment](/docs/tutorial/part-zero/) from the Gatsby docs
+- [Set Up Your Development Environment](/docs/tutorial/part-0/) from the Gatsby docs

docs/docs/how-to/adding-common-features/add-500-page.md

@@ -0,0 +1,11 @@
+---
+title: Adding a 500 Page
+---
+
+To add a 500 page create a page whose path matches the regex `^\/?500\/?$` (`/500/`, `/500`, `500/` or `500`), most often you'll want to create a React component page at `src/pages/500.js`.
+
+Users will see the 500 error page when runtime errors happen in the [`getServerData` function](/docs/reference/rendering-options/server-side-rendering/) of your page.
+
+Gatsby ensures that your 500 page is built as `500.html`. [Gatsby Cloud](/products/cloud/) supports displaying this custom 500 page. If you're hosting your site another way you'll need to set up a custom rule to serve this file for 500 errors.
+
+When developing using `gatsby develop`, you can still preview your 500 page by going to `localhost:8000/500`.

docs/docs/how-to/images-and-media/preprocessing-external-images.md

@@ -2,7 +2,7 @@
 title: Preprocessing External Images
 ---
 
-Gatsby allows powerful image processing features using the [`Sharp`](https://github.com/lovell/sharp/) library to automatically process images to be performant, with features like lazy-loading. That said, this only works if the image is a `File` node in the GraphQL layer.
+Gatsby allows powerful image processing features using the [`sharp`](https://github.com/lovell/sharp/) library to automatically process images to be performant, with features like lazy-loading. That said, this only works if the image is a `File` node in the GraphQL layer.
 
 If you want the same functionality for files that are remotely hosted online and not located in your Git repo, [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/) has an API called `createRemoteFileNode` to solve this.
 
@@ -24,7 +24,7 @@ featuredImgAlt: Mountains with a starry sky
 Hello World
 ```
 
-You can use a custom Frontmatter field for the URL of the featured image you want to pull down and use as part of the site.
+You can use a custom frontmatter field for the URL of the featured image you want to pull down and use as part of the site.
 
 By default, this is a string value as you haven't told Gatsby yet how to interpret it. However, you can add some code into `gatsby-node.js` to modify it.
 
@@ -43,7 +43,7 @@ exports.createSchemaCustomization = ({ actions }) => {
   createTypes(`
     type MarkdownRemark implements Node {
       frontmatter: Frontmatter
-      featuredImg: File @link(from: "featuredImg___NODE")
+      featuredImg: File @link(from: "fields.localFile")
     }
 
     type Frontmatter {
@@ -56,7 +56,7 @@ exports.createSchemaCustomization = ({ actions }) => {
 
 exports.onCreateNode = async ({
   node,
-  actions: { createNode },
+  actions: { createNode, createNodeField },
   store,
   cache,
   createNodeId,
@@ -66,7 +66,7 @@ exports.onCreateNode = async ({
     node.internal.type === "MarkdownRemark" &&
     node.frontmatter.featuredImgUrl !== null
   ) {
-    let fileNode = await createRemoteFileNode({
+    const fileNode = await createRemoteFileNode({
       url: node.frontmatter.featuredImgUrl, // string that points to the URL of the image
       parentNodeId: node.id, // id of the parent node of the fileNode you are going to create
       createNode, // helper function in gatsby-node to generate the node
@@ -75,20 +75,20 @@ exports.onCreateNode = async ({
       store, // Gatsby's Redux store
     })
 
-    // if the file was created, attach the new node to the parent node
+    // if the file was created, extend the node with "localFile"
     if (fileNode) {
-      node.featuredImg___NODE = fileNode.id
+      createNodeField({ node, name: "localFile", value: fileNode.id })
     }
   }
 }
 ```
 
 Going step by step through the code:
 
-1. Define some types for `MarkdownRemark` using the Schema Customization API. For `featuredImg`, use the `from` argument to point the `link` extension to the correct field name (with a `___NODE` suffix), [more details about foreign-key fields here](/docs/reference/graphql-data-layer/schema-customization/#foreign-key-fields). Defining a field for alternative text as `featuredImgAlt` can also improve accessibility, in addition to providing context for the image if it fails to load.
+1. Define some types for `MarkdownRemark` using the Schema Customization API. For `featuredImg`, use the `from` argument to point the `link` extension to the correct field name (the `createNodeField` extends the node with a `fields` key), [more details about foreign-key fields here](/docs/reference/graphql-data-layer/schema-customization/#foreign-key-fields). Defining a field for alternative text as `featuredImgAlt` can also improve accessibility, in addition to providing context for the image if it fails to load.
 2. Create an `onCreateNode` function so you can watch for when `MarkdownRemark` nodes are made.
 3. Use `createRemoteFileNode` by passing in the various required fields and get a reference to the file afterwards.
-4. If the Node is created, attach it as a child of the original Node. `___NODE` tells the GraphQL layer that the name before it is going to be a field on the parent Node that links to another Node. To do this, pass the `id` as the reference. Do note, this new node is now attached to the root of the `markdownRemark` node instead of the `frontmatter` field.
+4. If the Node is created, extend the node with a `localFile` field. To do this, pass the `id` as the reference. Do note, this new node is now attached to the root of the `markdownRemark` node instead of the `frontmatter` field as `fields`.
 
 And since it is a File Node, `gatsby-transformer-sharp` will pick it up and create a `childImageSharp` child Node inside this newly created Node.
 
@@ -114,38 +114,38 @@ query {
 
 ![GraphiQL with above query inserted](../../images/remote-file-node-graphiql-preview.png)
 
-You can then use `gatsby-transformer-sharp` to fill in the query for a fixed image here. For more information on transforming images using parameters and fragments, check out the [Gatsby Image API docs](/docs/reference/built-in-components/gatsby-image/).
+You can then use `gatsby-transformer-sharp` & `gatsby-plugin-image` to fill in the query for a fixed image here. For more information on transforming images using parameters and fragments, check out the ["Using Gatsby Plugin Image" guide](/docs/how-to/images-and-media/using-gatsby-plugin-image/).
 
 ```graphql
 query {
   allMarkdownRemark {
     nodes {
       featuredImg {
         childImageSharp {
-          fixed(width: 600) {
-            ...GatsbyImageSharpFixed
-          }
+          gatsbyImageData(width: 600, layout: FIXED)
         }
       }
     }
   }
 }
 ```
 
-And finally, you can update the template for this blog post to include a featured image node. Note the alt text still comes from the post frontmatter. This template is based on the one in the [Programmatically create pages from data](/docs/tutorial/part-seven/) section of the Gatsby Tutorial.
+And finally, you can update the template for this blog post to include a featured image node. Note the alt text still comes from the post frontmatter. This template is based on the one in the [Programmatically create pages from data](/docs/tutorial/part-7/) section of the Gatsby Tutorial.
 
 ```jsx
 import React from "react"
-import Img from "gatsby-image"
+import { GatsbyImage } from "gatsby-plugin-image"
 import { graphql } from "gatsby"
 
 const template = ({ data }) => {
   return (
     <>
       <h1>{data.markdownRemark.frontmatter.title}</h1>
       {data.markdownRemark.featuredImg && (
-        <Img
-          fixed={data.markdownRemark.featuredImg.childImageSharp.fixed}
+        <GatsbyImage
+          image={
+            data.markdownRemark.featuredImg.childImageSharp.gatsbyImageData
+          }
           alt={data.markdownRemark.frontmatter.featuredImgAlt}
         />
       )}
@@ -166,9 +166,7 @@ export const query = graphql`
       html
       featuredImg {
         childImageSharp {
-          fixed(width: 600) {
-            ...GatsbyImageSharpFixed
-          }
+          gatsbyImageData(width: 600, layout: FIXED)
         }
       }
     }

docs/docs/how-to/images-and-media/using-cloudinary-image-service.md

@@ -19,7 +19,7 @@ Dealing with images on the web has always been a problem as unoptimized images c
 Cloudinary provides a couple of amazing solutions to this problem, namely:
 
 - Remote storage and delivery of images via CDN
-- Offers a wider range of transformations than [gatsby-image](/docs/how-to/images-and-media/using-gatsby-image/).
+- Offers a wider range of transformations than [gatsby-plugin-image](/docs/how-to/images-and-media/using-gatsby-plugin-image/).
 - [Digital Asset Management](https://cloudinary.com/documentation/digital_asset_management_overview) for enterprise assets
 
 ## Gatsby-source-cloudinary

docs/docs/how-to/local-development/starters.md

@@ -31,6 +31,6 @@ gatsby develop
 ## Additional resources
 
 - Follow a [more detailed guide](/docs/starters/) on using Gatsby starters.
-- Learn how to use the [Gatsby CLI](/docs/reference/gatsby-cli) tool to use starters in [tutorial part one](/docs/tutorial/part-one/#using-gatsby-starters)
+- Learn how to use the [Gatsby CLI](/docs/reference/gatsby-cli) tool to use starters in [tutorial part one](/docs/tutorial/part-1/#using-gatsby-starters)
 - Browse the [Starter Library](/starters/?v=2)
 - Check out Gatsby's [official default starter](https://github.com/gatsbyjs/gatsby-starter-default)

docs/docs/how-to/local-development/troubleshooting-common-errors.md

@@ -36,7 +36,7 @@ Here are some examples of plugins that require you to install more than just the
 - [gatsby-plugin-styled-components](/plugins/gatsby-plugin-styled-components/): `styled-components`, and `babel-plugin-styled-components`
 - [gatsby-plugin-sass](/plugins/gatsby-plugin-sass/): `node-sass`, or `sass`
 - [gatsby-plugin-material-ui](/plugins/gatsby-plugin-material-ui/): `@material-ui/styles`
-- [gatsby-image](/plugins/gatsby-image/): `gatsby-transformer-sharp`, and `gatsby-plugin-sharp`
+- [gatsby-plugin-image](/plugins/gatsby-plugin-image/): `gatsby-source-filesystem`, `gatsby-transformer-sharp`, and `gatsby-plugin-sharp`
 
 Rather than packaging up the other dependent libraries alongside these plugins, they can stay smaller in size when they are published and are able to rely on alternative implementations. One example is `gatsby-plugin-sass` that can use either the Node.js or Dart implementations of Sass.
 
@@ -129,7 +129,7 @@ Comparing your GraphQL query to your site's schema in `http://localhost:8000/___
 
 - neither any source plugins you are using nor your own implementation of the [`sourceNodes` API](/docs/reference/config-files/gatsby-node/#sourceNodes) are misconfigured
 
-## Errors using gatsby-image and sharp
+## Errors using gatsby-plugin-image and sharp
 
 Gatsby's image processing is broken up into different packages which need to work together to source images and transform them into different optimized versions. You might run into these errors getting them to play together nicely.
 
@@ -158,9 +158,7 @@ allMdx {
     title
     image {
       childImageSharp {
-        fluid {
-          srcSet
-        }
+        gatsbyImageData
       }
     }
   }

docs/docs/how-to/performance/improving-build-performance.md

@@ -32,6 +32,10 @@ many fields that aren't needed to create the pages. Most sites only need to quer
 
 Check how long `createPages` takes for your build. If it's longer than 10s, check if there's fields you can remove from the query.
 
+#### Query only need fields in page queries
+
+The more fields you query the longer each query will take to run. Gatsby's GraphQL schema gives you a rich array of filtering/sorting capabilities so you grab just the data you need. If you install [gatsby-plugin-perf-budgets](https://github.com/pieh/gatsby-plugin-perf-budgets), it will show you the amount of data you query for each page so you can audit larger ones.
+
 #### Make sure you're not clearing the cache between builds
 
 In the past, Gatsby's cache was less reliable than it is now. As a result, some sites started clearing the cache between builds. With improvements we've made, that should not be necessary anymore, so if your build script says something like "gatsby clean && gatsby build" you may want to change it to just run gatsby build.

docs/docs/how-to/performance/improving-site-performance.md

@@ -192,13 +192,13 @@ Font optimizations are usually small, but easy performance wins.
 
 Media files are often the largest files on a site, and so can delay page load significantly while they are pulled over the network, especially if their location is not well-defined.
 
-[Gatsby Plugin Image](/docs/how-to/images-and-media/using-gatsby-image/) is our approach to optimizing image loading performance. It does three basic things:
+[Gatsby Plugin Image](/docs/how-to/images-and-media/using-gatsby-plugin-image/) is our approach to optimizing image loading performance. It does three basic things:
 
 1. It delays non-essential work for images not above the fold to avoid resource congestion.
 2. It provides a placeholder during image fetch.
 3. It minimizes image file size to reduce request roundtrip time.
 
-The `gatsby-plugin-image` documentation is fairly exhaustive, ranging from [why image optimization is important](/docs/conceptual/using-gatsby-image/), or [how to implement Gatsby Plugin Image](/docs/how-to/images-and-media/using-gatsby-plugin-image/), to a [Gatsby Image reference](/docs/reference/built-in-components/gatsby-image/).
+The `gatsby-plugin-image` documentation is fairly exhaustive, ranging from [why image optimization is important](/docs/conceptual/using-gatsby-image/) to [how to implement Gatsby Plugin Image](/docs/how-to/images-and-media/using-gatsby-plugin-image/).
 
 Implementing Gatsby Image is typically the bulk of image- and media-related performance optimization.
 

docs/docs/how-to/plugins-and-themes/creating-a-source-plugin.md

@@ -3,6 +3,8 @@ title: "Creating a Source Plugin"
 tableOfContentsDepth: 2
 ---
 
+import { Announcement } from "gatsby-interface"
+
 In this tutorial, you'll create your own source plugin that will gather data from an API. The plugin will source data, optimize remote images, and create foreign key relationships between data sourced by your plugin.
 
 ## What is a source plugin?
@@ -426,7 +428,7 @@ Each node of post data has an `imgUrl` field with the URL of an image on Unsplas
 
 You can read about [how to use Gatsby Image to prevent image bloat](/docs/how-to/images-and-media/using-gatsby-image/) if you are unfamiliar with it.
 
-#### Create `remoteFileNode`'s from a URL
+#### Create remote file node from a URL
 
 To create optimized images from URLs, `File` nodes for image files need to be added to your site's data. Then, you can install `gatsby-plugin-sharp` and `gatsby-transformer-sharp` which will automatically find image files and add the data needed for `gatsby-image`.
 
@@ -461,7 +463,7 @@ Then export a new function `onCreateNode`, and call `createRemoteFileNode` in it
 // called each time a node is created
 exports.onCreateNode = async ({
   node, // the node that was just created
-  actions: { createNode },
+  actions: { createNode, createNodeField },
   createNodeId,
   getCache,
 }) => {
@@ -476,7 +478,7 @@ exports.onCreateNode = async ({
     })
 
     if (fileNode) {
-      node.remoteImage___NODE = fileNode.id
+      createNodeField({ node, name: 'localFile', value: fileNode.id })
     }
   }
 }
@@ -486,29 +488,42 @@ This code is called every time a node is created, e.g. when `createNode` is invo
 
 ```javascript:title=source-plugin/gatsby-node.js
 if (fileNode) {
-  // save the ID of the fileNode on the Post node
-  node.remoteImage___NODE = fileNode.id
+  createNodeField({ node, name: 'localFile', value: fileNode.id })
 }
 ```
 
-By assigning a field called `remoteImage___NODE` to the ID of the `File` node that was created, Gatsby will be able to [infer](/docs/glossary#inference) a connection between this field and the file node. This will allow fields on the file to be queried from the post node.
+By using [`createNodeField`](/docs/reference/config-files/actions/#createNodeField) you're extending the existing node and place a new field named `localFile` under the `fields` key.
 
-```graphql
-# leaving off the ___NODE field will give you:
-query {
-  allPost {
-    nodes {
-      id
-      remoteImage # returns an ID like "ecd83d94-7111-5386-bd3f-0066248b6fa9"
+<Announcement style={{marginBottom: "1.5rem"}}>
+
+**Note:** Do not mutate the `node` directly and use `createNodeField` instead. Otherwise the change won't be persisted and you might see inconsistent data. This behavior changed with Gatsby 4, read the [migration guide](/docs/reference/release-notes/migrating-from-v3-to-v4/#dont-mutate-nodes-outside-of-expected-apis) to learn more.
+
+</Announcement>
+
+In the previous step you only defined the `fileNode.id` as a `value` but at this time Gatsby can't just yet resolve this to the `fileNode` (and susequently the image) itself. Therefore, you'll need to create a foreign-key relationship between the `Post` node and the respective `File` node. Use the [`createSchemaCustomization`](/docs/reference/config-files/gatsby-node/#createSchemaCustomization) API to define this relationship:
+
+```javascript:title=source-plugin/gatsby-node.js
+exports.createSchemaCustomization = ({ actions }) => {
+  const { createTypes } = actions
+
+  createTypes(`
+    type Post implements Node {
+      localFile: File @link(from: "fields.localFile")
     }
-  }
+  `)
 }
-# instead of an entire node you can query more fields on:
+```
+
+_**Note**: You can use [schema customization APIs](/docs/reference/graphql-data-layer/schema-customization/#foreign-key-fields) to create these kinds of connections between nodes as well as sturdier and more strictly typed ones._
+
+You now can query the image like this:
+
+```graphql
 query {
   allPost {
     nodes {
       id
-      remoteImage {
+      localFile {
         id
         relativePath
       }
@@ -517,8 +532,6 @@ query {
 }
 ```
 
-_**Note**: you can use [schema customization APIs](/docs/reference/graphql-data-layer/schema-customization) to create these kinds of connections between nodes as well as sturdier and more strictly typed ones._
-
 At this point you have created local image files from the remote locations and associated them with your posts, but you still need to transform the files into optimized versions.
 
 #### Transform `File` nodes with sharp plugins
@@ -547,13 +560,13 @@ module.exports = {
 
 By installing the sharp plugins in the site, they'll run after the source plugin and transform the file nodes and add fields for the optimized versions at `childImageSharp`. The transformer plugin looks for `File` nodes with extensions like `.jpg` and `.png` to create optimized images and creates the GraphQL fields for you.
 
-Now when you run your site, you will also be able to query a `childImageSharp` field on the `post.remoteImage`:
+Now when you run your site, you will also be able to query a `childImageSharp` field on the `post.localFile`:
 
 ```graphql
 query {
   allPost {
     nodes {
-      remoteImage {
+      localFile {
         // highlight-start
         childImageSharp {
           id
@@ -569,7 +582,7 @@ With data available, you can now query optimized images to use with the `gatsby-
 
 ### Create foreign key relationships between data
 
-To link the posts to the authors, Gatsby needs to be aware that the two are associated, and how. You have already implemented one example of this when Gatsby inferred a connection between a `remoteImage` and the remote file from Unsplash.
+To link the posts to the authors, Gatsby needs to be aware that the two are associated, and how. You have already implemented one example of this when Gatsby inferred a connection between a `localFile` and the remote file from Unsplash.
 
 The best approach for connecting related data is through customizing the GraphQL schema. By implementing the `createSchemaCustomization` API, you can specify the exact shape of a node's data. While defining that shape, you can optionally link a node to other nodes to create a relationship.
 
@@ -585,32 +598,22 @@ exports.createSchemaCustomization = ({ actions }) => {
       description: String!
       imgUrl: String!
       imgAlt: String!
-      # create relationships between Post and File nodes for optimized images
-      remoteImage: File @link
       # create relationships between Post and Author nodes
       author: Author @link(from: "author.name" by: "name")
+      # Created in previous step
+      localFile: @link(from: "fields.localFile")
     }
     type Author implements Node {
       id: ID!
       name: String!
-    }`)
+    }
+  `)
 }
 ```
 
 The `author: Author @link(from: "author.name" by: "name")` line tells Gatsby to look for the value on the `Post` node at `post.author.name` and relate it with an `Author` node with a matching `name`. This demonstrates the ability to link using more than just an ID.
 
-The line `remoteImage: File @link` tells Gatsby to look for a `remoteImage` field on a `Post` node and link it to a `File` node with the ID there.
-
-Now, instead of using inference in for the `remoteImage` field, you can take off the `___NODE` suffix. You can update the code in the `onCreateNode` API now like this:
-
-```diff:title=source-plugin/gatsby-node.js
-  if (fileNode) {
--   node.remoteImage___NODE = fileNode.id
-+   node.remoteImage = fileNode.id
-  }
-```
-
-Now running the site will allow you to query authors and remoteImages from the post nodes!
+Now running the site will allow you to query authors from the post nodes!
 
 ```graphql
 query {
@@ -621,9 +624,6 @@ query {
       author {
         name
       }
-      remoteImage {
-        id
-      }
       // highlight-end
     }
   }
@@ -666,7 +666,7 @@ export default ({ data }) => (
           <span>By: {post.author.name}</span>
           <p>{post.description}</p>
           <Img
-            fluid={post.remoteImage.childImageSharp.fluid}
+            fluid={post.localFile?.childImageSharp?.fluid}
             alt={post.imgAlt}
           />
         </div>
@@ -687,7 +687,7 @@ export const query = graphql`
           id
           name
         }
-        remoteImage {
+        localFile {
           id
           childImageSharp {
             id

docs/docs/how-to/querying-data/page-query.md

@@ -78,7 +78,7 @@ const HomePage = () => {
 
 The first part of writing the GraphQL query is including the operation (in this case "`query`") along with a name.
 
-From [exploring in the GraphQL IDE, GraphiQL](/docs/tutorial/part-five/#introducing-graphiql/), you've learned that one of the types that you can query is `site`, which in turn has its own `siteMetadata` field with subfields that correspond to the data provided in `gatsby-config.js`.
+From [exploring in the GraphQL IDE, GraphiQL](/docs/tutorial/part-5/#introducing-graphiql/), you've learned that one of the types that you can query is `site`, which in turn has its own `siteMetadata` field with subfields that correspond to the data provided in `gatsby-config.js`.
 
 Putting this together, the completed query looks like:
 

docs/docs/how-to/querying-data/running-queries-with-graphiql.md

@@ -47,6 +47,6 @@ The environment variable `ENABLE_GATSBY_REFRESH_ENDPOINT` enables a "Refresh Dat
 
 ## Other resources
 
-- See [Tutorial Part 5: Source Plugins](/docs/tutorial/part-five/) for a more complete example of using GraphiQL
+- See [Tutorial Part 5: Source Plugins](/docs/tutorial/part-5/) for a more complete example of using GraphiQL
 - See the [README for GraphiQL](https://github.com/graphql/graphiql)
 - See [Using GraphQL Playground](/docs/using-graphql-playground/) for another example of a GraphQL IDE

docs/docs/how-to/querying-data/using-gatsby-without-graphql.md

@@ -94,7 +94,7 @@ Using Gatsby's data layer provides the following benefits:
 
 Working outside of the data layer also means foregoing the optimizations provided by transformer plugins, like:
 
-- [`gatsby-image`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-image) (speedy optimized images),
+- [`gatsby-plugin-image`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-image) (speedy optimized images),
 - [`gatsby-transformer-sharp`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-sharp) (provides queryable fields for processing your images in a variety of ways including resizing, cropping, and creating responsive images),
 - ... the whole Gatsby ecosystem of official and community-created [transformer plugins](/plugins/?=transformer).
 

docs/docs/how-to/rendering-options/using-deferred-static-generation.md

@@ -0,0 +1,101 @@
+---
+title: Using Deferred Static Generation (DSG)
+---
+
+## Introduction
+
+Deferred Static Generation (DSG) is one of [Gatsby's rendering options](/docs/conceptual/rendering-options/) and allows you to defer non-critical page generation to user request, speeding up build times. Instead of generating _every_ page at build time, you can decide to build certain pages up front and others only when a user accesses the page at run time. For large sites, with content that is infrequently visited (e.g. old blog posts or certain content types), this can dramatically reduce build times.
+
+In this guide, you'll learn how to modify your `createPage` calls to only build your preferred pages up-front and leave the rest deferred to the first user request.
+
+For full documentation on all options, see the [Reference Guide on Deferred Static Generation](/docs/reference/rendering-options/deferred-static-generation/).
+
+## Prerequisites
+
+Before you begin, you should already have:
+
+- An existing Gatsby site. (Need help creating one? Follow the [Quick Start](/docs/quick-start/).)
+- A `gatsby-node.js` file where you're creating pages with the [`createPages`](/docs/reference/config-files/gatsby-node#createPages) API. (The [File System Route API](/docs/reference/routing/file-system-route-api) isn't yet supported, but it will be soon!)
+
+## Directions
+
+The general process for using DSG looks like this:
+
+- Adding `defer: true` to your `createPage` call.
+
+  ```js
+  createPage({
+    path: "page-path",
+    component: "component-path",
+    context: {},
+    defer: true, // highlight-line
+  })
+  ```
+
+For the purpose of this guide, let's assume you have a blog powered by MDX and have blog posts dating back years (with 1000 blog posts in total). Via your analytics tracking, you're seeing that only the latest 100 posts are regularly visited. The rest gets occasional or no visits at all.
+
+The `gatsby-node.js` file:
+
+```js:title=gatsby-node.js
+const blogPostTemplate = require.resolve(`./src/templates/blog-post.js`)
+
+export.createPages = async ({ graphql, actions, reporter }) => {
+  const { createPage } = actions
+
+  const result = await graphql(`
+    query {
+      allMdx(sort: { fields: frontmatter___date, order: DESC }) {
+        nodes {
+          slug
+        }
+      }
+    }
+  `)
+
+  if (result.errors) {
+    reporter.panicOnBuild(`There was an error loading posts`, result.errors)
+    return
+  }
+
+  const posts = result.data.allMdx.nodes
+
+  posts.forEach(post => {
+    createPage({
+      path: post.slug,
+      component: blogPostTemplate,
+      context: {
+        slug: post.slug,
+      },
+    })
+  })
+}
+```
+
+For this example, it's important that inside the `gatsby-node.js` the result is sorted by date and in an descending order. Depending on your use case you might need to adjust the query to sort differently or query additional information (e.g. a "category" field from the frontmatter) besides the `slug`.
+
+This way you can use the `index` in the `forEach` to apply `defer` to all but the latest 100 posts:
+
+```js:title=gatsby-node.js
+// Rest of gatsby-node.js
+
+const posts = result.data.allMdx.nodes
+
+posts.forEach((post, index) => {
+  createPage({
+    path: post.slug,
+    component: blogPostTemplate,
+    context: {
+      slug: post.slug,
+    },
+    // index is zero-based index
+    defer: index + 1 > 100, // highlight-line
+  })
+})
+```
+
+The first 100 pages will receive `defer: false`, the other 900 pages receive `defer: true`.
+
+## Additional Resources
+
+- [API Reference guide](/docs/reference/rendering-options/deferred-static-generation/)
+- [Conceptual Guide](/docs/conceptual/rendering-options/)

docs/docs/how-to/rendering-options/using-server-side-rendering.md

@@ -0,0 +1,121 @@
+---
+title: Using Server-side Rendering (SSR)
+---
+
+## Introduction
+
+Server-side Rendering (SSR) is one of [Gatsby's rendering options](/docs/conceptual/rendering-options/) and allows you to pre-render a page with data that is fetched when a user visits the page. While it is recommended to use [Static Site Generation (SSG)](/docs/conceptual/rendering-options#static-site-generation-ssg) or [Deferred Static Generation (DSG)](/docs/conceptual/rendering-options#deferred-static-generation-dsg) over SSR you might have use cases that require it, e.g. dynamic personalization, authenticated data, A/B testing, configurability based on location or user data. If you don't need to pre-render the page you can use [client-only routes](/docs/how-to/routing/client-only-routes-and-user-authentication/).
+
+In this guide, you'll learn how to use `getServerData`, fetch an image from a dog API, and display it dynamically on the page.
+
+For full documentation on all options, see [the reference guide](/docs/reference/rendering-options/server-side-rendering/).
+
+## Prerequisites
+
+Before you begin, you should already have:
+
+- An existing Gatsby site. (Need help creating one? Follow the [Quick Start](/docs/quick-start/).)
+
+## Directions
+
+The general process for using SSR looks like this:
+
+1. Adding `getServerData` function
+2. Requesting data inside `getServerData` & displaying it
+
+To follow this guide, create a new page at `src/pages/ssr.js`.
+
+### Step 1: Adding `getServerData` function
+
+By adding an async function called `getServerData` to your page, you tell Gatsby to choose the SSR rendering option. Add it to your new page:
+
+```js:title=src/pages/ssr.js
+import * as React from "react"
+
+const SSRPage = () => (
+  <main>
+    <h1>SSR Page with Dogs</h1>
+  </main>
+)
+
+export default SSRPage
+
+export async function getServerData() {} // highlight-line
+```
+
+### Step 2: Requesting data inside `getServerData` & displaying it
+
+You can execute anything you want inside the `getServerData` function, but you need to return an object containing `props`. You then can access the data as a `serverData` prop inside your page component (similarly to how page queries automatically pass in a `data` prop to page components).
+
+Use `fetch` to pull data from the [dog.ceo API](https://dog.ceo/):
+
+```js:title=src/pages/ssr.js
+// The rest of the page
+
+export async function getServerData() {
+  try {
+    const res = await fetch(`https://dog.ceo/api/breeds/image/random`)
+
+    if (!res.ok) {
+      throw new Error(`Response failed`)
+    }
+
+    return {
+      props: await res.json(),
+    }
+  } catch (error) {
+    return {
+      headers: {
+        status: 500,
+      },
+      props: {}
+    }
+  }
+}
+```
+
+Every time a user visits the page now the URL `https://dog.ceo/api/breeds/image/random` is requested and the response available as `serverData` to the page. The API gives back the response in the shape of `{ "message": "img-url", "status": "" }`.
+
+Display the image using the data from the API now:
+
+```js:title=src/pages/ssr.js
+import * as React from "react"
+
+const SSRPage = ({ serverData }) => ( // highlight-line
+  <main>
+    <h1>SSR Page with Dogs</h1>
+    {/* highlight-next-line */}
+    <img alt="Happy dog" src={serverData.message} />
+  </main>
+)
+
+export default SSRPage
+
+export async function getServerData() {
+  try {
+    const res = await fetch(`https://dog.ceo/api/breeds/image/random`)
+
+    if (!res.ok) {
+      throw new Error(`Response failed`)
+    }
+
+    return {
+      props: await res.json(),
+    }
+  } catch (error) {
+    return {
+      headers: {
+        status: 500,
+      },
+      props: {}
+    }
+  }
+}
+```
+
+If you haven't already, start `gatsby develop` and visit `http://localhost:8000/ssr`. Refreshing the page should give you a new dog image on every refresh.
+
+## Additional Resources
+
+- [API Reference Guide](/docs/reference/rendering-options/server-side-rendering/)
+- [Conceptual Guide](/docs/conceptual/rendering-options/)

docs/docs/how-to/routing/layout-components.md

@@ -59,7 +59,7 @@ Alternatively, you can prevent your layout component from unmounting by using [g
 
 ## Other resources
 
-- [Creating nested layout components in Gatsby](/docs/tutorial/part-three/)
+- [Creating nested layout components in Gatsby](/docs/tutorial/part-3/)
 - [Life after layouts in Gatsby V2](/blog/2018-06-08-life-after-layouts/)
 - [Migrating from v1 to v2](/docs/reference/release-notes/migrating-from-v1-to-v2/#remove-or-refactor-layout-components)
 - [gatsby-plugin-layout](/plugins/gatsby-plugin-layout/)

docs/docs/how-to/sourcing-data/sourcing-from-contentful.md

@@ -31,6 +31,10 @@ npm install gatsby-source-contentful
 
 ## How to use
 
+To get setup quickly with a new site and have Gatsby Cloud do the heavy lifting, [deploy a new Gatsby Contentful site with just a few clicks on gatsbyjs.com](https://www.gatsbyjs.com/dashboard/deploynow?url=https://github.com/contentful/starter-gatsby-blog).
+
+For more detailed instructions on manually configuring your Gatsby Contentful site for production builds and Preview builds visit [the Gatsby Cloud knowledgebase](https://support.gatsbyjs.com/hc/en-us/articles/360056047134-Add-the-Gatsby-Cloud-App-to-Contentful).
+
 ### With the Delivery API
 
 ```javascript:title=gatsby-config.js

docs/docs/how-to/styling/css-modules.md

@@ -71,4 +71,4 @@ performance benefits like only bundling referenced code.
 
 ## How to build a page using CSS Modules
 
-Visit the [CSS Modules section of the tutorial](/docs/tutorial/part-two/#css-modules) for a guided tour of building a page with CSS Modules.
+Visit the [CSS Modules section of the tutorial](/docs/tutorial/part-2/#css-modules) for a guided tour of building a page with CSS Modules.

docs/docs/how-to/styling/global-css.md

@@ -8,7 +8,7 @@ Globally-scoped CSS rules are declared in external `.css` stylesheets, and [CSS
 
 ## Adding global styles with a layout component
 
-The best way to add global styles is with a [shared layout component](/docs/tutorial/part-three/#your-first-layout-component). This layout component is used for things that are shared throughout the site, including styles, header components, and other common items.
+The best way to add global styles is with a [shared layout component](/docs/tutorial/part-3/#your-first-layout-component). This layout component is used for things that are shared throughout the site, including styles, header components, and other common items.
 
 > **NOTE:** This pattern is implemented by default in [the default starter](https://github.com/gatsbyjs/gatsby-starter-default/blob/063978d59f74103da45d5880a61ebd2e77798e3c/src/components/layout.js#L13).
 

docs/docs/linking-between-pages.md

@@ -59,5 +59,5 @@ It is also recommended to include a [visual icon](https://thenounproject.com/ter
 
 ## Other resources
 
-- For the complete example of how to link between pages, see [Part One](/docs/tutorial/part-one/#linking-between-pages/) in the Tutorial
+- For the complete example of how to link between pages, see [Part One](/docs/tutorial/part-1/#linking-between-pages/) in the Tutorial
 - Check out more detail on routing in Gatsby in the [API doc for Gatsby Link](/docs/reference/built-in-components/gatsby-link/).

docs/docs/porting-an-html-site-to-gatsby.md

@@ -41,7 +41,7 @@ No [client-side](/docs/glossary#client-side) JavaScript (e.g jQuery etc.) is on
 
 ### Development environment
 
-Gatsby generates websites and web applications for production through a compilation and build process, and it also has tools optimized for local development. To set up the Gatsby [CLI](/docs/glossary#cli) and development environment (if you haven't already) check out [Part Zero of the Gatsby tutorial](/docs/tutorial/part-zero/).
+Gatsby generates websites and web applications for production through a compilation and build process, and it also has tools optimized for local development. To set up the Gatsby [CLI](/docs/glossary#cli) and development environment (if you haven't already) check out [Part Zero of the Gatsby tutorial](/docs/tutorial/part-0/).
 
 ### Gatsby Project
 

docs/docs/preparing-your-environment.md

@@ -4,11 +4,11 @@ title: Preparing Your Environment
 
 To get started with Gatsby, you'll need to make sure you have the following software tools installed:
 
-1. [Node.js](/docs/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system)
-2. [npm CLI](/docs/tutorial/part-zero/#check-your-nodejs-installation)
-3. [Gatsby CLI](/docs/tutorial/part-zero/#using-the-gatsby-cli)
+1. [Node.js](/docs/tutorial/part-0/#install-nodejs-for-your-appropriate-operating-system)
+2. [npm CLI](/docs/tutorial/part-0/#check-your-nodejs-installation)
+3. [Gatsby CLI](/docs/tutorial/part-0/#using-the-gatsby-cli)
 
-For step-by-step installation instructions and detailed explanations of the required software, head on over to the [Gatsby tutorial](/docs/tutorial/part-zero/).
+For step-by-step installation instructions and detailed explanations of the required software, head on over to the [Gatsby tutorial](/docs/tutorial/part-0/).
 
 The [quick start](/docs/quick-start/) is also available for intermediate to advanced developers.
 

docs/docs/query-behind-the-scenes.md

@@ -4,7 +4,7 @@ title: How Queries Work
 
 In Gatsby, GraphQL queries are specified as tagged `graphql` expressions. These can be exported in your page source files, used in the `StaticQuery` component, or used in the `useStaticQuery` hook in your React code. Plugins can also define fragments for use in queries.
 
-Note that the process outlined in this section only applies to queries that are specified in components or templates. It does _not_ apply to queries specified in a `gatsby-node.js` file which are typically used for the creation of dynamic pages. (For an example of a query in a `gatsby-node.js` file, check out the [Creating Pages](/docs/tutorial/part-seven/#creating-pages) section from Part 7 of the Gatsby tutorial.
+Note that the process outlined in this section only applies to queries that are specified in components or templates. It does _not_ apply to queries specified in a `gatsby-node.js` file which are typically used for the creation of dynamic pages. (For an example of a query in a `gatsby-node.js` file, check out the [Creating Pages](/docs/tutorial/part-7/#creating-pages) section from Part 7 of the Gatsby tutorial.
 
 Most code to do with queries is in the [src/query](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby/src/query) directory in the Gatsby monorepo.
 

docs/docs/recipes/deploying-your-site.md

@@ -46,7 +46,7 @@ gatsby build && gatsby serve
 
 ### Additional resources
 
-- Walk through building and deploying an example site in [tutorial part one](/docs/tutorial/part-one/#deploying-a-gatsby-site)
+- Walk through building and deploying an example site in [tutorial part one](/docs/tutorial/part-1/#deploying-a-gatsby-site)
 - Learn about [performance optimization](/docs/performance/)
 - Read about [other deployment related topics](/docs/preparing-for-deployment/)
 - Check out the [deployment docs](/docs/deploying-and-hosting/) for specific hosting platforms and how to deploy to them

docs/docs/recipes/pages-layouts.md

@@ -153,7 +153,7 @@ export default function Home() {
 
 ### Additional resources
 
-- Create a layout component in [tutorial part three](/docs/tutorial/part-three/#your-first-layout-component)
+- Create a layout component in [tutorial part three](/docs/tutorial/part-3/#your-first-layout-component)
 - Styling with [Layout Components](/docs/how-to/routing/layout-components/)
 
 ## Creating pages programmatically with createPage
@@ -244,6 +244,6 @@ export default function DogTemplate({ pageContext: { dog } }) {
 
 ### Additional resources
 
-- Tutorial section on [programmatically creating pages from data](/docs/tutorial/part-seven/)
+- Tutorial section on [programmatically creating pages from data](/docs/tutorial/part-7/)
 - Reference guide on [using Gatsby without GraphQL](/docs/how-to/querying-data/using-gatsby-without-graphql/)
 - [Example repo](https://github.com/gatsbyjs/gatsby/tree/master/examples/recipe-createPage) for this recipe

docs/docs/recipes/querying-data.md

@@ -429,7 +429,6 @@ Fragments can be nested inside other fragments, and multiple fragments can be us
 
 - [Example repo using fragments](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-fragments)
 - [Gatsby GraphQL reference for fragments](/docs/graphql-reference/#fragments)
-- [Gatsby image fragments](/docs/reference/built-in-components/gatsby-image/#image-query-fragments)
 - [Example repo with co-located data](https://github.com/gatsbyjs/gatsby/tree/master/examples/gatsbygram)
 
 ## Querying data client-side with `fetch`

docs/docs/recipes/sourcing-data.md

@@ -57,7 +57,7 @@ query MyPokemonQuery {
 
 ### Additional resources
 
-- Walk through an example using the `gatsby-source-filesystem` plugin in [tutorial part five](/docs/tutorial/part-five/#source-plugins)
+- Walk through an example using the `gatsby-source-filesystem` plugin in [tutorial part five](/docs/tutorial/part-5/#source-plugins)
 - Search available source plugins in the [Gatsby library](/plugins/?=source)
 - Understand source plugins by building one in the [source plugin tutorial](/docs/how-to/plugins-and-themes/creating-a-source-plugin/)
 - The createNode function [documentation](/docs/reference/config-files/actions/#createNode)
@@ -202,7 +202,7 @@ export const pageQuery = graphql`
 
 ### Additional resources
 
-- [Tutorial: Programmatically create pages from data](/docs/tutorial/part-seven/)
+- [Tutorial: Programmatically create pages from data](/docs/tutorial/part-7/)
 - [Creating and modifying pages](/docs/creating-and-modifying-pages/)
 - [Adding Markdown pages](/docs/how-to/routing/adding-markdown-pages/)
 - [Guide to creating pages from data programmatically](/docs/programmatically-create-pages-from-data/)
@@ -633,4 +633,4 @@ export const query = graphql`
 
 - [Using Decoupled Drupal with Gatsby](/blog/2018-08-13-using-decoupled-drupal-with-gatsby/)
 - [More on sourcing from Drupal](/docs/how-to/sourcing-data/sourcing-from-drupal)
-- [Tutorial: Programmatically create pages from data](/docs/tutorial/part-seven/)
+- [Tutorial: Programmatically create pages from data](/docs/tutorial/part-7/)

docs/docs/recipes/styling-css.md

@@ -50,7 +50,7 @@ import "./src/styles/global.css"
 
 ### Directions
 
-You can add global styles to a [shared layout component](/docs/tutorial/part-three/#your-first-layout-component). This component is used for things that are common throughout the site, like a header or footer.
+You can add global styles to a [shared layout component](/docs/tutorial/part-3/#your-first-layout-component). This component is used for things that are common throughout the site, like a header or footer.
 
 1. If you don't already have one, create a new directory in your site at `/src/components`.
 
@@ -89,7 +89,7 @@ export default function Home() {
 ### Additional resources
 
 - [Standard Styling with Global CSS Files](/docs/how-to/styling/global-css/)
-- [More about layout components](/docs/tutorial/part-three)
+- [More about layout components](/docs/tutorial/part-3)
 
 ## Using Styled Components
 
@@ -213,7 +213,7 @@ Notice that the file extension is `.module.css` instead of `.css`, which tells G
 
 ### Additional resources
 
-- More on [Using CSS Modules](/docs/tutorial/part-two/#css-modules)
+- More on [Using CSS Modules](/docs/tutorial/part-2/#css-modules)
 - [Live example on Using CSS modules](https://github.com/gatsbyjs/gatsby/blob/master/examples/using-css-modules)
 
 ## Using Sass/SCSS

docs/docs/recipes/transforming-data.md

@@ -53,7 +53,7 @@ export const query = graphql`
 
 ### Additional resources
 
-- [Tutorial on transforming Markdown to HTML](/docs/tutorial/part-six/#transformer-plugins) using `gatsby-transformer-remark`
+- [Tutorial on transforming Markdown to HTML](/docs/tutorial/part-6/#transformer-plugins) using `gatsby-transformer-remark`
 - Browse available transformer plugins in the [Gatsby plugin library](/plugins/?=transformer)
 
 ## Transforming images into grayscale using GraphQL

docs/docs/reference/config-files/gatsby-config.md

@@ -66,7 +66,7 @@ module.exports = {
 
 This way you can store it in one place, and pull it whenever you need it. If you ever need to update the info, you only have to change it here.
 
-See a full description and sample usage in [Gatsby.js Tutorial Part Four](/docs/tutorial/part-four/#data-in-gatsby).
+See a full description and sample usage in [Gatsby.js Tutorial Part Four](/docs/tutorial/part-4/#data-in-gatsby).
 
 ## Plugins
 
@@ -355,3 +355,23 @@ See more about [Proxying API Requests in Develop](/docs/api-proxy/).
 ## Advanced proxying with `developMiddleware`
 
 See more about [adding develop middleware](/docs/api-proxy/#advanced-proxying).
+
+## jsxRuntime
+
+Setting to "automatic" allows the use of JSX without having to import React. More information can be found on the [Introducing the new JSX Transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) blog post.
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  jsxRuntime: "automatic",
+}
+```
+
+## jsxImportSource
+
+With the new jsxRuntime you can set which package React should use as underlying jsx transformer. For example you can set it to "@emotion/react" so by default @emotion/react is used instead of the react package.
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  jsxImportSource: "@emotion/react",
+}
+```

docs/docs/reference/functions/getting-started.md

@@ -34,6 +34,13 @@ A Function file must export a single function that takes two parameters:
 - `req`: Node's [http request object](https://nodejs.org/api/http.html#http_class_http_incomingmessage) with some [automatically parsed data](/docs/reference/functions/getting-started/#common-data-formats-are-automatically-parsed)
 - `res`: Node's [http response object](https://nodejs.org/api/http.html#http_class_http_serverresponse) with some [extra helper functions](/docs/reference/functions/middleware-and-helpers/#res-helpers)
 
+Dynamic routing is supported for creating REST-ful APIs and other uses cases
+
+- `/api/users` => `src/api/users/index.js`
+- `/api/users/23` => `src/api/users/[id].js`
+
+[Learn more about dynamic routes.](/docs/reference/functions/routing#dynamic-routing)
+
 ## Typescript
 
 Functions can be written in JavaScript or Typescript.
@@ -202,5 +209,4 @@ Shadowing with functions works similar to how shadowing works in general. You ca
 
 ## Limitations
 
-- Gatsby Functions do not support dynamic routes in Gatsby Cloud at the moment
 - Bundling in native dependencies is not supported at the moment

docs/docs/reference/functions/routing.md

@@ -4,9 +4,43 @@ title: Routing
 
 Function routing shares the same syntax as [page routing](/docs/reference/routing/file-system-route-api/).
 
+## Static Routing
+
 Both top-level and nested routes are supported.
 
 - `src/api/top-level.js` => `/api/top-level`
 - `src/api/directory/foo.js` => `/api/directory/foo`
 
 `index.js` files are routed at their directory path e.g. `src/api/users/index.js` => `/api/users`
+
+## Dynamic Routing
+
+### Param routes
+
+Use square brackets (`[ ]`) in the file path to mark dynamic segments of the URL.
+
+So to create an Function for fetching user information by `userId`:
+
+```js:title=src/api/users/[id].js
+export default async function handler(req, res) {
+  const userId = req.params.id
+  // Fetch user
+  const user = await getUser(userId)
+  res.json(user)
+}
+```
+
+Dynamic routes share syntax with [client-only routes](/docs/reference/routing/file-system-route-api/#creating-client-only-routes).
+
+### Splat routes
+
+Gatsby also supports splat (or wildcard) routes, which are routes that will match anything after the splat. These are less common, but still have use cases.
+
+```js:title=src/api/foo/[...].js
+export default function handler(req, res) {
+  const params = req.params[`*`].split(`/`)
+
+  // `src/api/foo/1/2 // params[0] === `1`
+  // params[1] === `2`
+}
+```

docs/docs/reference/graphql-data-layer/schema-customization.md

@@ -364,18 +364,6 @@ schema.buildObjectType({
 
 #### Foreign-key fields
 
-Gatsby's automatic type inference has one trick up its sleeve: for every field
-that ends in `___NODE` it will interpret the field value as an `id` and create a
-foreign-key relation.
-
-> Note: Before the introduction of the Schema Customization APIs in Gatsby v2.2,
-> there were two mechanisms to create links between node types: a plugin author would use the `___NODE`
-> fieldname convention (for plugins), and a user would define [mappings](/docs/reference/config-files/gatsby-config/#mapping-node-types) between fields in their `gatsby-config.js`. Both users and plugin authors can now use the `@link` extension described below.
-
-Creating foreign-key relations with the `createTypes` action,
-i.e. without relying on type inference and the `___NODE` field naming
-convention, requires a bit of manual setup.
-
 In the example project, the `frontmatter.author` field on
 `MarkdownRemark` nodes to expand the provided field value to a full `AuthorJson` node.
 For this to work, there has to be provided a custom field resolver. (see below for
@@ -478,11 +466,6 @@ For the above example you can read `@link` this way: Use the value from the fiel
 
 Keep in mind that in the example above, the link of `posts` in `AuthorJson` works because `frontmatter` and `author` are both objects. If, for example, the `Frontmatter` type had a list of `authors` instead (`frontmatter.authors.email`), it wouldn't work since the `by` argument doesn't support arrays. In that case, you'd have to provide a custom resolver with [Gatsby Type Builders](/docs/reference/graphql-data-layer/schema-customization/#gatsby-type-builders) or [createResolvers API](/docs/reference/graphql-data-layer/schema-customization/#createresolvers-api).
 
-> Note that when using `createTypes` to fix type inference for a foreign-key field
-> created by a plugin, the underlying data will probably live on a field with
-> a `___NODE` suffix. Use the `from` argument to point the `link` extension to
-> the correct field name. For example: `author: [AuthorJson] @link(from: "author___NODE")`.
-
 #### Extensions and directives
 
 Out of the box, Gatsby provides [four extensions](/docs/reference/config-files/actions/#createTypes)

docs/docs/reference/release-notes/migrating-source-plugin-from-v3-to-v4.md

@@ -0,0 +1,297 @@
+---
+title: Upgrade Your Source Plugins for Gatsby 4
+---
+
+import { Announcement } from "gatsby-interface"
+
+Gatsby 4 is here! Following on the heels of Gatsby 3, Gatsby 4 further improves build performance and introduces new parallel processing capabilities. In the guide below, we'll walk you through preparing your source plugin for Gatsby 4. You'll find this guide useful if you are a maintainer for a source plugin (as opposed to a consumer using a source plugin in your Gatsby site).
+
+Introducing support for Gatsby 4 in your source plugin can be accomplished by ensuring your code adopts the 4 following changes. Many plugins already had the majority of their code organized the way it needed to be!
+
+With Gatsby 4, Core APIs are being split into different processes so they're able to run simultaneously in parallel instead of sequentially. Early results show at least 40% improvement of build performance. Gatsby 4 also lays the groundwork for two new options of rendering your Gatsby site: Server Side Rendering (SSR) and Deferred Static Generation (DSG) to scale Gatsby to infinity and beyond.
+
+It's time to get into it! The rest of this guide outlines the breaking changes in Gatsby 4 and some quick ways to resolve them. Find something confusing? Let us know in the [GitHub discussion](https://github.com/gatsbyjs/gatsby/discussions/33199) and we'll respond as fast as possible.
+
+<Announcement style={{marginBottom: "1.5rem"}}>
+
+**Looking for examples of source plugins that support Gatsby 4?** Check out [`gatsby-source-wordpress`](/plugins/gatsby-source-wordpress/) and [`gatsby-source-shopify`](/plugins/gatsby-source-shopify/).
+
+</Announcement>
+
+## 1. Modification to Gatsby's GraphQL schema during `sourceNodes` is not allowed
+
+There are three APIs that can modify Gatsby's GraphQL schema: [`createTypes`](/docs/reference/config-files/actions/#createTypes), [`addThirdPartySchema`](/docs/reference/config-files/actions/#addThirdPartySchema), [`createFieldExtension`](/docs/reference/config-files/actions/#createFieldExtension). In Gatsby 4, you're no longer allowed to use these APIs during the [`sourceNodes`](/docs/reference/config-files/gatsby-node/#sourceNodes) lifecycle. Please use them in the [`createSchemaCustomization`](/docs/reference/config-files/gatsby-node/#createSchemaCustomization) lifecycle instead.
+
+### The Old Way
+
+`createTypes` is used inside `sourceNodes`.
+
+```javascript:title=gatsby-node.js
+exports.sourceNodes = ({ actions }) => { // highlight-line
+  const { createTypes } = actions;
+
+  createTypes(`
+    type AuthorJson implements Node {
+      joinedAt: Date
+    }
+  `)
+}
+```
+
+### The New Way
+
+`createTypes` is used instead in `createSchemaCustomization`
+
+```javascript:title=gatsby-node.js
+exports.createSchemaCustomization = ({ actions }) => { // highlight-line
+  const { createTypes } = actions;
+
+  createTypes(`
+    type AuthorJson implements Node {
+      joinedAt: Date
+    }
+  `)
+}
+```
+
+## 2. Data mutations need to happen during `sourceNodes` or `onCreateNode`
+
+Creation or augmentation of nodes needs to happen in the appropriate APIs. In Gatsby 4, creating nodes inside resolvers is not allowed. You need to create them in `sourceNodes` and add expensive operations inside your resolvers.
+
+### The Old Way
+
+A node is created at the same time a resolver is created.
+
+```javascript:title=gatsby-node.js
+exports.createResolvers = ({ // highlight-line
+  createNodeId,
+  actions,
+  createResolvers,
+  store,
+  cache,
+  reporter,
+}) => {
+  createResolvers({
+    CustomImage: {
+      localImage: {
+        type: "File!",
+        resolve: async (source, args, context, info) => {
+          return createRemoteFileNode({ // highlight-line
+            url: source.url,
+            parentNodeId: source.id,
+            store,
+            cache,
+            createNode: actions.createNode,
+            createNodeId,
+            reporter,
+          })
+        },
+      },
+    },
+  })
+}
+```
+
+### The New Way
+
+The type is created in `createSchemaCustomization` and then referenced inside `sourceNodes` to create the node.
+
+```javascript:title=gatsby-node.js
+exports.createSchemaCustomization = ({ actions }) => {
+  const { createTypes } = actions;
+
+  createTypes(`
+    type CustomImage implements Node {
+      localImage: File @link
+    }
+  `)
+}
+
+exports.sourceNodes = async ({ // highlight-line
+  actions,
+  createNodeId,
+  createContentDigest,
+  store,
+  cache,
+  reporter,
+}) => {
+  const { createNode } = actions
+
+  // code to fetch data
+
+  for (const { url } of remoteImages) {
+    const nodeId = createNodeId(`my-data-${url}`)
+    const image = await createRemoteFileNode({ // highlight-line
+      url: url,
+      parentNodeId: nodeId,
+      store,
+      cache,
+      createNode,
+      createNodeId,
+      reporter,
+    })
+    const node = {
+      id: nodeId,
+      parent: null,
+      children: [],
+      url,
+      localImageId: image.id,
+      internal: {
+        type: `CustomImage`,
+        content: url,
+        contentDigest: createContentDigest(url),
+      },
+    }
+
+    createNode(node)
+  }
+}
+```
+
+## 3. Global state
+
+As stated above, Gatsby 4 improves build times by running GraphQL queries in parallel. Running multiple processes means global variables might not contain the data that you hoped they would.
+
+When a new process (worker) gets created, the new [`onPluginInit`](/docs/reference/config-files/gatsby-node/#onPluginInit) lifecycle method is run, which can be used to restore global state if needed.
+
+### The Old Way
+
+`onPreBootstrap` (or `onPreInit`) is setting global state so that other functions can access that global state.
+
+```javascript:title=gatsby-node.js
+let globalPluginOptions = {}
+
+exports.onPreBootstrap = (_, pluginOptions) => { // highlight-line
+  globalPluginOptions = pluginOptions
+}
+
+function aDeepNestedFunction(arg) {
+  if (globalPluginOptions.convert) {
+    return arg.toUpperCase()
+  } else {
+    return arg
+  }
+}
+```
+
+### The New Way
+
+To check if the new `onPluginInit` lifecycle is available, you can use the `isGatsbyNodeLifecycleSupported` from the [`gatsby-plugin-utils`](https://www.npmjs.com/package/gatsby-plugin-utils) package. (Make sure to add this explicitly to your dependencies by running `npm install gatsby-plugin-utils`!) This will help you keep backwards compatibility with Gatsby 3 while moving forward to a Gatsby 4 world. You'll also need to check if you are using the `stable` or `unstable` version of `onPluginInit`.
+
+```javascript:title=gatsby-node.js
+let coreSupportsOnPluginInit: "unstable" | "stable" | undefined
+
+try {
+  const { isGatsbyNodeLifecycleSupported } = require(`gatsby-plugin-utils`)
+  if (isGatsbyNodeLifecycleSupported(`onPluginInit`)) {
+    coreSupportsOnPluginInit = "stable"
+  } else if (isGatsbyNodeLifecycleSupported(`unstable_onPluginInit`)) {
+    coreSupportsOnPluginInit = "unstable"
+  }
+} catch (e) {
+  console.error(`Could not check if Gatsby supports onPluginInit lifecycle`)
+}
+
+let globalPluginOptions = {}
+
+const initializeGlobalState = (_, pluginOptions) => {
+  globalPluginOptions = pluginOptions
+}
+
+if (coreSupportsOnPluginInit === "stable") {
+  exports.onPluginInit = initializeGlobalState // highlight-line
+} else if (coreSupportsOnPluginInit === "unstable") {
+  exports.unstable_onPluginInit = initializeGlobalState // highlight-line
+} else {
+  exports.onPreBootstrap = initializeGlobalState // highlight-line
+}
+
+function aDeepNestedFunction(arg) {
+  if (globalPluginOptions.convert) {
+    return arg.toUpperCase()
+  } else {
+    return arg
+  }
+}
+```
+
+## 4. Custom error map needs to be initiated in `onPluginInit`
+
+To make it more clear for users when things go wrong, Gatsby has structured logs. It allows plugins to properly guide people to a solution by providing metadata such as URLs to docs. This feature needs to be initialized in `onPluginInit` to allow GraphQL resolvers to report these errors.
+
+### The Old Way
+
+`onPreInit` is setting the error map.
+
+```javascript:title=gatsby-node.js
+const ERROR_MAP = {
+  [CODES.Generic]: {
+    text: context => context.sourceMessage,
+    level: `ERROR`,
+    type: `PLUGIN`,
+  },
+  [CODES.MissingResource]: {
+    text: context => context.sourceMessage,
+    level: `ERROR`,
+    type: `PLUGIN`,
+    category: `USER`,
+  },
+}
+exports.onPreInit = ({ reporter }) => { // highlight-line
+  if (reporter.setErrorMap) {
+    reporter.setErrorMap(ERROR_MAP)
+  }
+}
+```
+
+### The New Way
+
+Similar to handling [global state](#3-global-state), you can use the `isGatsbyNodeLifecycleSupported` helper function from [`gatsby-plugin-utils`](https://www.npmjs.com/package/gatsby-plugin-utils) to check if the new [`onPluginInit`](/docs/reference/config-files/gatsby-node/#onPluginInit) lifecycle method is available. (Make sure to add this explicitly to your dependencies by running `npm install gatsby-plugin-utils`!) This will help you keep backwards compatibility with Gatsby 3 while moving forward to a Gatsby 4 world. You'll also need to check if you are using the `stable` or `unstable` version of `onPluginInit`.
+
+```javascript:title=gatsby-node.js
+let coreSupportsOnPluginInit: "unstable" | "stable" | undefined
+
+try {
+  const { isGatsbyNodeLifecycleSupported } = require(`gatsby-plugin-utils`)
+  if (isGatsbyNodeLifecycleSupported(`onPluginInit`)) {
+    coreSupportsOnPluginInit = "stable"
+  } else if (isGatsbyNodeLifecycleSupported(`unstable_onPluginInit`)) {
+    coreSupportsOnPluginInit = "unstable"
+  }
+} catch (e) {
+  console.error(`Could not check if Gatsby supports onPluginInit lifecycle`)
+}
+
+const ERROR_MAP = {
+  [CODES.Generic]: {
+    text: context => context.sourceMessage,
+    level: `ERROR`,
+    type: `PLUGIN`,
+  },
+  [CODES.MissingResource]: {
+    text: context => context.sourceMessage,
+    level: `ERROR`,
+    type: `PLUGIN`,
+    category: `USER`,
+  },
+}
+
+const initializePlugin = ({ reporter }) => {
+  if (reporter.setErrorMap) {
+    reporter.setErrorMap(ERROR_MAP)
+  }
+}
+
+// need to conditionally export otherwise it throws an error for older versions
+if (coreSupportsOnPluginInit === "stable") {
+  exports.onPluginInit = initializePlugin // highlight-line
+} else if (coreSupportsOnPluginInit === "unstable") {
+  exports.unstable_onPluginInit = initializePlugin // highlight-line
+} else {
+  exports.onPreInit = initializePlugin // highlight-line
+}
+```
+
+## Recommendations for publishing your new source plugin version
+
+Publish a new version of your Gatsby-4-compatible package that references `"gatsby": "^4.0.0"` in its `peerDependencies` to signal that the given source plugin version is specifically updated to work with Gatsby 4.

docs/docs/reference/rendering-options/deferred-static-generation.md

@@ -0,0 +1,57 @@
+---
+title: Deferred Static Generation API
+---
+
+> **Note:** This feature requires running NodeJS server.
+> It is currently fully supported with [`gatsby serve`](/docs/reference/gatsby-cli/#serve) and in [Gatsby Cloud](/products/cloud/).
+
+Deferred Static Generation (DSG) allows you to defer non-critical page generation to the first user request, speeding up build times.
+Instead of generating _every_ page up front, you can decide to generate certain pages at build time and others only when a user accesses the page for the first time.
+Subsequent page requests use the same HTML and JSON generated during the very first request to this page.
+
+## Creating deferred pages
+
+Creating deferred pages is almost identical to [creating regular pages](/docs/reference/routing/creating-routes/#using-gatsby-nodejs).
+The only difference is the new `defer` argument for [`createPage` action](/docs/reference/config-files/actions/#createPage).
+When set to `true`, it tells Gatsby to exclude the page from the build step and instead generate it during the first HTTP request:
+
+```js:title=gatsby-node.js
+exports.createPages = async function ({ actions, graphql }) {
+  actions.createPage({
+    path: "/the-page-path/",
+    component: require.resolve("./src/templates/template.js"),
+    context: {},
+    defer: true, // highlight-line
+  })
+}
+```
+
+The `defer` argument is optional. If it's excluded, the page will be generated at build time by default.
+
+## Working with deferred pages locally
+
+Deferred static generation has no effect when using `gatsby develop`. You can work with pages locally as usual.
+
+If you want to test deferred generation specifically, run [`gatsby build`](/docs/reference/gatsby-cli/#build)
+and [`gatsby serve`](/docs/reference/gatsby-cli/#serve) from the command line. Deferred pages will be
+generated during the very first request to the page via `gatsby serve`.
+
+## Using in production
+
+Deferred static generation requires a running NodeJS server. You can put NodeJS running `gatsby serve`
+behind a content delivery network (CDN) like [Fastly](https://www.fastly.com/), however that also requires additional infrastructure (like monitoring, logging, and crash-recovery).
+
+Complete setup is available for you in [Gatsby Cloud](/products/cloud/) out-of-the-box.
+
+## How it works
+
+The first request against a deferred page is a cache miss because the HTML/JSON wasn't generated yet. On Gatsby Cloud the request is sent to a worker process that leverages an internal database to generate the data of the page. Once the page is generated it'll be sent back to the user immediately. In the background, all generated artifacts are stored so that on a second request the cached response is directly served from the CDN. For that it bypasses the worker process completely.
+
+When you directly visit a page you'll get served the HTML. If you request a page on client-side navigation through Gatsby's Link component the response will be JSON. Gatsby's router uses this to render the page on the client. In the background, the JSON is stored and the HTML is generated so that on a second request of the page (including a direct visit) the page can be served from the CDN.
+
+This all happens automatically and you only need to configure the `defer` key.
+
+## Additional Resources
+
+- [How-To Guide: Using Deferred Static Generation](/docs/how-to/rendering-options/using-deferred-static-generation/)
+- [Conceptual Guide: Rendering Options](/docs/conceptual/rendering-options/)

docs/docs/reference/rendering-options/server-side-rendering.md

@@ -0,0 +1,133 @@
+---
+title: Server-Side Rendering API
+---
+
+> **Note:** This feature requires running NodeJS server.
+> It is currently fully supported with [`gatsby serve`](/docs/reference/gatsby-cli/#serve) and in [Gatsby Cloud](/products/cloud/).
+
+Server-Side Rendering (SSR) allows you to render a page at run-time with data that is fetched when a user visits the page.
+The server generates the full HTML during HTTP request and sends it to the user. The API is focused on data fetching outside of the Gatsby data layer.
+
+## Creating server-rendered pages
+
+You can create server-rendered pages [the same way as regular pages](/docs/reference/routing/creating-routes/) (including using the File System Route API).
+
+The main difference is that page component must export an async function called `getServerData`:
+
+```js:title=src/pages/my-first-ssr-page.js
+export async function getServerData(context) {
+  return {
+    props: {}, // Will be passed to the page component as "serverData" prop
+    headers: {}, // HTTP response headers for this page
+  }
+}
+```
+
+When a page component exports `getServerData` function, Gatsby treats all pages built with this component
+as server-rendered.
+
+The `context` parameter is an object with the following keys:
+
+- `headers`: The request headers
+- `method`: The request method, e.g. `GET`
+- `url`: The request URL
+- `query`: An object representing the query string
+- `params`: If you use [File System Route API](/docs/reference/routing/file-system-route-api/) the URL path gets passed in as `params`. For example, if your page is at `src/pages/{Product.name}.js` the `params` will be an object like `{ name: 'value' }`.
+
+`getServerData` can return an object with two keys:
+
+- `props` (optional): Object containing the data passed to `serverData` page prop. Should be a serializable object.
+- `headers` (optional): Object containing `headers` that are sent to the browser and caching proxies/CDNs (e.g., cache headers).
+
+### Use `serverData` prop in React page component
+
+The `props` object you return from `getServerData` gets passed to the page component as `serverData` prop.
+
+```js:title=src/pages/get-random-dog.js
+import * as React from "react"
+
+const Page = ({ serverData }) => {
+  const { dogImage } = serverData
+
+  // Use dogImage in your page...
+}
+
+export async function getServerData() {
+  const res = await fetch(`https://dog.ceo/api/breeds/image/random`)
+  const data = await res.json()
+
+  return {
+    props: {
+      dogImage: data,
+    },
+  }
+}
+
+export default Page
+```
+
+## Interplay with build-time GraphQL queries
+
+Server-rendered pages also support regular Gatsby GraphQL page queries. The page query is executed at build time,
+and the data is passed to React component as a `data` prop on each render (along with the `serverData` prop).
+
+Keep in mind that `data` will be the same every time the page renders, but `serverData` will change according to return value of your `getServerData` function.
+Runtime GraphQL queries are not supported yet.
+
+```js:title=src/pages/get-random-dog.js
+import * as React from "react"
+
+const Page = ({ data, serverData }) => {
+  const { site } = data
+  const { dogImage } = serverData
+  // Use dogImage and site info in your page...
+}
+
+export const pageQuery = graphql`
+  query PageData {
+    site {
+      siteMetadata {
+        title
+      }
+    }
+  }
+`
+
+export async function getServerData() {
+  const res = await fetch(`https://dog.ceo/api/breeds/image/random`)
+  const data = await res.json()
+
+  return {
+    props: {
+      dogImage: data,
+    },
+  }
+}
+
+export default Page
+```
+
+## Working with server-rendered pages locally
+
+Server-rendered pages work with both `gatsby develop` and `gatsby serve`. The page will be
+re-generated on each request.
+
+## Using in production
+
+Server-Side Rendering requires a running NodeJS server. You can put NodeJS running `gatsby serve`
+behind a content delivery network (CDN) like [Fastly](https://www.fastly.com/), however that also requires additional infrastructure (like monitoring, logging, and crash-recovery).
+
+Complete setup with auto-scaling is available for you in [Gatsby Cloud](/products/cloud/) out-of-the-box.
+
+## How it works
+
+For SSR every request only runs on server-side. On Gatsby Cloud the request is sent to a worker process that runs your `getServerData` function, passes this data to React component and returns HTML back to the user. By default, every request is a cache miss and for caching you'll need to set custom HTTP Cache-Control headers.
+
+When you directly visit a page you'll get served the HTML. If you request a page on client-side navigation through Gatsby's Link component the response will be JSON. Gatsby's router uses this to render the page on the client.
+
+This all happens automatically and you'll only need to define a `getServerData` function in your page. You can't export it from non-page files.
+
+## Additional Resources
+
+- [How-To Guide: Server-Side Rendering](/docs/how-to/rendering-options/using-server-side-rendering/)
+- [Conceptual Guide: Rendering Options](/docs/conceptual/rendering-options/)

docs/docs/schema-generation.md

@@ -22,13 +22,13 @@ When users and plugins add types using `createTypes`, those types are added to t
 
 ## 3. Legacy schema customization
 
-Before schema customization was added, there were several ways that one could modify the schema. Those were the `createNodeField` action, `setFieldsOnGraphQLType` API and `graphql-config.js` mappings.
+Before schema customization was added, there were several ways that one could modify the schema. Those were the `createNodeField` action, `setFieldsOnGraphQLNodeType` API and `graphql-config.js` mappings.
 
 ### `createNodeField`
 
 This adds a field under the `fields` field. Plugins can't modify types that they haven't created, so you can use this method to add data to nodes that your plugin doesn't own. This doesn't modify the schema directly. Instead, those fields are picked by inference. There are no plans to deprecate this API at the moment.
 
-### `setFieldsOnGraphQLType`
+### `setFieldsOnGraphQLNodeType`
 
 This allows adding GraphQL Fields to any node type. This operates on GraphQL types itself and the syntax matches `graphql-js` field definitions. This API will be marked as deprecated in Gatsby v3, moved under a flag in Gatsby v4, and removed from Gatsby v5. `createTypes` and `addResolvers` should solve all the use cases for this API.
 

docs/docs/tutorial/part-0/index.mdx

@@ -53,14 +53,14 @@ In addition to the ones listed above, Gatsby uses a few more technologies under
 
 The rest of this part of the Tutorial walks you through how to install the following tools:
 
-* [Node.js](#nodejs) (v12.13 or newer)
+* [Node.js](#nodejs) (v14.15 or newer)
 * [Git](#git)
 * [Gatsby command line interface (CLI)](#gatsby-cli) (v3 or newer)
 * [Visual Studio Code](#vs-code)
 
 ### Node.js
 
-[Node.js](https://nodejs.dev/learn) is an environment that can run JavaScript code outside of a web browser. Gatsby is built with Node.js. To get up and running with Gatsby, you’ll need to have Node.js version 12.13 (or newer) installed on your computer.
+[Node.js](https://nodejs.dev/learn) is an environment that can run JavaScript code outside of a web browser. Gatsby is built with Node.js. To get up and running with Gatsby, you’ll need to have Node.js version 14.15 (or newer) installed on your computer.
 
 [npm](https://docs.npmjs.com/getting-started/what-is-npm) is a package manager that comes bundled with Node.js. You'll use the npm command line interface to add packages to your site (like Gatsby plugins) and to run command line tasks (like starting up your site).
 
@@ -304,7 +304,7 @@ It doesn't matter what code editor you choose to use. Your site will end up look
 
 ## Account Creation
 
-The final step in this part of the tutorial is to create accounts for the online platforms you will need to deploy your site online for others to see.
+The final step in this part of the Tutorial is to create accounts for the online platforms you will need to deploy your site online for others to see.
 
 In this Tutorial, you will deploy your site using Gatsby Cloud. To use Gatsby Cloud, you will need to set up a GitHub account and a Gatsby Cloud account. (Both accounts are free!)
 

docs/docs/tutorial/part-1/index.mdx

@@ -227,7 +227,7 @@ GitHub is a website that many developers use to back up and share their code onl
 3. To push your existing code from your computer to your new GitHub repository, enter the commands below in the command line. Be sure to swap out `YOUR_GITHUB_USERNAME` for your actual username and `YOUR_GITHUB_REPO_NAME` with the name you gave your GitHub repo (like `my-first-gatsby-site`).
 
    ```
-   git remote add origin git@github.com:YOUR_GITHUB_USERNAME/YOUR_GITHUB_REPO_NAME.git
+   git remote add origin https://github.com/YOUR_GITHUB_USERNAME/YOUR_GITHUB_REPO_NAME.git
    git branch -M main
    git push -u origin main
    ```
@@ -236,9 +236,9 @@ GitHub is a website that many developers use to back up and share their code onl
 
 **Using GitHub for the first time?**
 
-If you get an error about permissions when you try to push your code to GitHub for the first time, you might need to set up an SSH key for your GitHub account. This lets GitHub know that your computer has permission to push code changes to your remote repos.
+If you get an error about permissions when you try to push your code to GitHub for the first time, you might need to set up a **personal access token** for your GitHub account. This lets GitHub know that your computer has permission to push code changes to your remote repos.
 
-For instructions on how to set up an SSH key, follow GitHub's guide: [Connecting to GitHub with SSH](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh).
+For instructions on how to set up a personal access token, follow GitHub's guide: [Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). Your personal access token will need the **repo** scope to be able to push changes to your repository.
 
 </Announcement>
 

docs/docs/tutorial/part-4/index.mdx

@@ -680,6 +680,28 @@ query MyQuery {
 }
 ```
 
+<Collapsible
+  summary="Seeing more nodes than expected?"
+>
+
+If you're still using a `StaticImage` from an external URL (like `https://some-site/image.jpg`) on your home page, you'll see an extra node for that image show up in your GraphQL response. That's because `StaticImage` uses [`createRemoteFileNode`](https://www.gatsbyjs.com/plugins/gatsby-source-filesystem/#createremotefilenode) under the hood which creates a `File` node for each image it downloads. If you're only using images from your filesystem, you won't see the extra node.
+
+To get rid of it, you can update your GraphQL query to filter the File nodes using the `sourceInstanceName` field (which corresponds to the value of the `name` option you set for `gatsby-source-filesystem` in your `gatsby-config.js` file).
+
+```graphql:title=src/pages/blog.js
+query {
+  allFile(filter: {sourceInstanceName: {eq: "blog"}}) {
+    nodes {
+      name
+    }
+  }
+}
+```
+
+`filter` is an **argument** that gets passed into the `allFile` field. Some fields take arguments, which you can use to change the way that nodes get returned in your final GraphQL response.
+
+</Collapsible>
+
 ### Task: Use a page query to pull the list of post filenames into your blog page
 
 Now that you've built a GraphQL query that returns a list of your post filenames, it's time to render that data in your blog page!

docs/docs/tutorial/whats-next/index.mdx

@@ -21,6 +21,8 @@ Not sure where to start? Here are a few Gatsby features that weren't covered in
 * [Client-only routes](/docs/how-to/routing/client-only-routes-and-user-authentication): These are helpful for pages that require user authentication or that load different content based on URL query parameters.
 * [Gatsby Node APIs](/docs/reference/config-files/gatsby-node/): You can create a `gatsby-node.js` if you need more control over the nodes in the data layer or other parts of Gatsby's build process.
 * [Serverless functions](/docs/reference/functions/): Build APIs for your Gatsby site and run them in Gatsby Cloud. No extra server maintenance necessary!
+* [Deferred static generation](/docs/how-to/rendering-options/using-deferred-static-generation): Speed up your site's build time by waiting to generate low-traffic pages until users request them at run time.
+* [Server-side rendering](/docs/how-to/rendering-options/using-server-side-rendering/): Pre-render a page with data that gets fetched when a user visits the page. With server-side rendering, you can add features like dynamic personalization, A/B testing, or other configuration based on location or user data.
 
 ## Join the community
 

docs/docs/upgrading-node-js.md

@@ -35,7 +35,7 @@ There are multiple ways to update your version of Node.js depending on how you o
 
 This is the recommended way to install a newer version of Node.
 
-You will have Homebrew installed on your computer if you [followed part zero of the Gatsby tutorial](/docs/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system). Homebrew is a program that allows you to install specific versions of Node.js (and other software).
+You will have Homebrew installed on your computer if you [followed part zero of the Gatsby tutorial](/docs/tutorial/part-0/#install-nodejs-for-your-appropriate-operating-system). Homebrew is a program that allows you to install specific versions of Node.js (and other software).
 
 To update from Node.js 10 to Node.js 12 using Homebrew, open a terminal and run the following commands:
 

docs/docs/using-gatsby-professionally/setting-up-gatsby-without-gatsby-new.md

@@ -8,10 +8,10 @@ There are many Enterprise level companies that maintain an internal clone of the
 
 To get started with Gatsby, you’ll need to make sure you have the following software tools installed:
 
-1. [Node.js](/docs/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system)
-2. [Gatsby CLI](/docs/tutorial/part-zero/#using-the-gatsby-cli)
+1. [Node.js](/docs/tutorial/part-0/#install-nodejs-for-your-appropriate-operating-system)
+2. [Gatsby CLI](/docs/tutorial/part-0/#using-the-gatsby-cli)
 
-For step-by-step installation instructions and detailed explanations of the required software, head on over to the [Gatsby tutorial](/docs/tutorial/part-zero/).
+For step-by-step installation instructions and detailed explanations of the required software, head on over to the [Gatsby tutorial](/docs/tutorial/part-0/).
 
 After your developer environment is set up, you'll want to set up a new project folder.
 
@@ -66,4 +66,4 @@ cd ../../
 gatsby develop
 ```
 
-And that's it! You should now have your initial page running on `http://localhost:8000` with a GraphiQL IDE running on `http://localhost:8000/___graphql`. From here, you can follow the rest of the [Gatsby tutorial](/docs/tutorial/part-zero/#set-up-a-code-editor) starting with setting up a code editor to get the full experience of what Gatsby can offer.
+And that's it! You should now have your initial page running on `http://localhost:8000` with a GraphiQL IDE running on `http://localhost:8000/___graphql`. From here, you can follow the rest of the [Gatsby tutorial](/docs/tutorial/part-0/#set-up-a-code-editor) starting with setting up a code editor to get the full experience of what Gatsby can offer.

docs/docs/working-with-images-in-markdown.md

@@ -8,7 +8,7 @@ When building Gatsby sites composed primarily of Markdown pages or posts, insert
 
 In sites like a blog, you may want to include a featured image that appears at the top of a page. One way to do this is to grab the image filename from a frontmatter field and then transform it with `gatsby-plugin-sharp` in a GraphQL query.
 
-This solution assumes you already have programmatically generated pages from Markdown with renderers like `gatsby-transformer-remark` or `gatsby-plugin-mdx`. If not, take a read through up to [Part 7 of the Gatsby Tutorial](/docs/tutorial/part-seven/). This will build upon the tutorial and as such, `gatsby-transformer-remark` will be used for this example.
+This solution assumes you already have programmatically generated pages from Markdown with renderers like `gatsby-transformer-remark` or `gatsby-plugin-mdx`. If not, take a read through up to [Part 7 of the Gatsby Tutorial](/docs/tutorial/part-7/). This will build upon the tutorial and as such, `gatsby-transformer-remark` will be used for this example.
 
 > Note: This can be done similarly using [MDX](/docs/how-to/routing/mdx/) as well. Instead of the `markdownRemark` nodes in GraphQL, `Mdx` can be swapped in and should work.
 

docs/tutorial/e-commerce-with-datocms-and-snipcart/index.md

@@ -25,11 +25,11 @@ You can sign up for the following accounts now or as you need to use each of the
 - [Snipcart](https://snipcart.com/): add a shopping cart to your site
 - [Netlify](https://www.netlify.com/): host your site and register a domain
 
-To edit code locally (affecting files stored on your computer), you'll need the following software. If you don't already know what these are or want additional background information, check out [Step 0 of the Gatsby tutorial](/docs/tutorial/part-zero/). It includes detailed instructions on how to set up a local development environment.
+To edit code locally (affecting files stored on your computer), you'll need the following software. If you don't already know what these are or want additional background information, check out [Step 0 of the Gatsby tutorial](/docs/tutorial/part-0/). It includes detailed instructions on how to set up a local development environment.
 
 - [Node.js](https://nodejs.org): run JavaScript on your computer
 - [Git](https://git-scm.com/downloads): track changes to your code
-- [Gatsby command line interface (CLI)](/docs/tutorial/part-zero/#using-the-gatsby-cli): run Gatsby commands on your computer
+- [Gatsby command line interface (CLI)](/docs/tutorial/part-0/#using-the-gatsby-cli): run Gatsby commands on your computer
 
 ## Provisioning Your Site on Gatsby Cloud
 

docs/tutorial/remark-plugin-tutorial.md

@@ -16,7 +16,7 @@ In certain instances, a developer may want to customize the content of the Markd
 
 There a few things that you should have some understanding with:
 
-- How to work with Remark in Gatsby as described in [Part Six](/docs/tutorial/part-six/) and [Part Seven](/docs/tutorial/part-seven/) of the Gatsby Tutorial.
+- How to work with Remark in Gatsby as described in [Part Six](/docs/tutorial/part-6/) and [Part Seven](/docs/tutorial/part-7/) of the Gatsby Tutorial.
 - Understanding of the Markdown Syntax.
 
 ## Understanding the Abstract Syntax Tree
@@ -323,7 +323,7 @@ A real-world example of this would be [`gatsby-remark-responsive-iframe`](https:
 
 ## Loading in changes and seeing effect
 
-At this point, our plugin is now ready to be used. To see the resulting functionality, it is helpful to re-visit [Part 7 of the Gatsby Tutorial](/docs/tutorial/part-seven/) to programmatically create pages from Markdown data. Once this is set up, you can examine that your plugin works as seen below based on the markdown you wrote earlier.
+At this point, our plugin is now ready to be used. To see the resulting functionality, it is helpful to re-visit [Part 7 of the Gatsby Tutorial](/docs/tutorial/part-7/) to programmatically create pages from Markdown data. Once this is set up, you can examine that your plugin works as seen below based on the markdown you wrote earlier.
 
 ![Output](../docs/images/remark-ast-output.png)
 

docs/tutorial/wordpress-source-plugin-tutorial.md

@@ -215,7 +215,7 @@ To do this, you need to:
 1. Create pages for each blog post
 2. Link up the title on the index page with the post page.
 
-If you haven't already, please read through [Part 7](/docs/tutorial/part-seven/) of the foundational tutorial, as it goes through the concept and examples of this process with Markdown instead of WordPress.
+If you haven't already, please read through [Part 7](/docs/tutorial/part-7/) of the foundational tutorial, as it goes through the concept and examples of this process with Markdown instead of WordPress.
 
 ### Creating pages for each blog post
 
@@ -247,7 +247,7 @@ exports.createPages = ({ graphql, actions }) => {
 }
 ```
 
-Next, [stop and restart](/docs/tutorial/part-zero/#view-your-site-locally) the `gatsby develop` environment. As you watch the terminal you should see two Post objects log to the terminal:
+Next, [stop and restart](/docs/tutorial/part-0/#view-your-site-locally) the `gatsby develop` environment. As you watch the terminal you should see two Post objects log to the terminal:
 
 ![Two posts logged to the terminal](./images/wordpress-source-plugin-log.jpg)
 

e2e-tests/contentful/cypress/integration/download-local.js

@@ -0,0 +1,13 @@
+describe(`downloadLocal`, () => {
+  beforeEach(() => {
+    cy.visit("/download-local").waitForRouteChange()
+  })
+
+  it(`renders dynamic image from static directory`, () => {
+    cy.get("#gatsby-plugin-image-download-local").should("be.visible")
+    cy.get("#gatsby-plugin-image-download-local").should("have.attr", "srcset")
+    cy.get("#gatsby-plugin-image-download-local")
+      .should("have.attr", "src")
+      .should("match", /^\/static/)
+  })
+})

e2e-tests/contentful/gatsby-config.js

@@ -12,9 +12,11 @@ module.exports = {
         spaceId: `k8iqpp6u0ior`,
         accessToken: `hO_7N0bLaCJFbu5nL3QVekwNeB_TNtg6tOCB_9qzKUw`,
         enableTags: true,
+        downloadLocal: true,
       },
     },
     `gatsby-transformer-remark`,
+    `gatsby-transformer-sharp`,
     `gatsby-transformer-sqip`,
     `gatsby-plugin-image`,
     `gatsby-plugin-sharp`,

e2e-tests/contentful/src/pages/download-local.js

@@ -0,0 +1,34 @@
+import { graphql } from "gatsby"
+import { GatsbyImage } from "gatsby-plugin-image"
+import * as React from "react"
+
+import Layout from "../components/layout"
+
+const DownloadLocalPage = ({ data }) => {
+  return (
+    <Layout>
+      <h1>Test downloadLocal feature</h1>
+      <GatsbyImage
+        id="gatsby-plugin-image-download-local"
+        image={data.contentfulAsset.localFile.childImageSharp.gatsbyImageData}
+      />
+    </Layout>
+  )
+}
+
+export default DownloadLocalPage
+
+export const pageQuery = graphql`
+  query DownloadLocalQuery {
+    contentfulAsset(contentful_id: { eq: "3BSI9CgDdAn1JchXmY5IJi" }) {
+      contentful_id
+      title
+      localFile {
+        absolutePath
+        childImageSharp {
+          gatsbyImageData
+        }
+      }
+    }
+  }
+`

e2e-tests/contentful/src/pages/index.js

@@ -14,6 +14,9 @@ const IndexPage = () => (
       <li>
         <Link to="/gatsby-plugin-image">/gatsby-plugin-image</Link>
       </li>
+      <li>
+        <Link to="/download-local">/download-local</Link>
+      </li>
     </ul>
     <h2>Content Rendering</h2>
     <ul>

e2e-tests/development-runtime/README.md

@@ -35,7 +35,7 @@ _Have another more specific idea? You may want to check out our vibrant collecti
 
     Your site is now running at `http://localhost:8000`!
 
-    \_Note: You'll also see a second link: `http://localhost:8000/___graphql`. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-five/#introducing-graphiql).\_
+    \_Note: You'll also see a second link: `http://localhost:8000/___graphql`. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-5/#introducing-graphiql).\_
 
     Open the `my-default-starter` directory in your code editor of choice and edit `src/pages/index.js`. Save your changes and the browser will update in real time!
 

e2e-tests/development-runtime/cypress/integration/eslint-rules/limited-exports-page-templates.js

@@ -23,7 +23,7 @@ describe(`limited-exports-page-templates`, () => {
   it(`should initially not log to console`, () => {
     cy.get(`@hmrConsoleLog`).should(
       `not.be.calledWithMatch`,
-      /13:1 {2}warning {2}In page templates only a default export of a valid React component and the named export of a page query is allowed./i
+      /13:1 {2}warning {2}In page templates only a default export of a valid React component and the named exports of a page query, getServerData or config are allowed./i
     )
   })
   it(`should log warning to console for invalid export`, () => {
@@ -34,11 +34,11 @@ describe(`limited-exports-page-templates`, () => {
 
     cy.get(`@hmrConsoleLog`).should(
       `be.calledWithMatch`,
-      /13:1 {2}warning {2}In page templates only a default export of a valid React component and the named export of a page query is allowed./i
+      /13:1 {2}warning {2}In page templates only a default export of a valid React component and the named exports of a page query, getServerData or config are allowed./i
     )
     cy.get(`@hmrConsoleLog`).should(
       `not.be.calledWithMatch`,
-      /15:1 {2}warning {2}In page templates only a default export of a valid React component and the named export of a page query is allowed./i
+      /15:1 {2}warning {2}In page templates only a default export of a valid React component and the named exports of a page query, getServerData or config are allowed./i
     )
   })
 })

examples/ecommerce-tutorial-with-stripe/README.md

@@ -23,6 +23,6 @@ This is a Gatsby e-commerce example based on https://www.gatsbyjs.com/tutorial/e
 - run `npm install`
 - run `gatsby develop`
 
-### 💫 Deploy with Netlify
+### 💫 Build, Preview, and Deploy to Gatsby Cloud
 
-[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/thorsten-stripe/ecommerce-gatsby-tutorial)
+[<img src="https://www.gatsbyjs.com/deploynow.png" alt="Deploy to Gatsby Cloud">](https://www.gatsbyjs.com/dashboard/deploynow?url=https://github.com/thorsten-stripe/ecommerce-gatsby-tutorial)