.gitignore

@@ -51,6 +51,7 @@ __diff_output__/
 # misc
 .serverless/
 .eslintcache
+scripts/.env
 
 # lock files
 yarn.lock

README.md

@@ -7,12 +7,14 @@
   Gatsby v3
 </h1>
 
-<h3 align="center">
+<p align="center">
   ⚛️ 📄 🚀
-</h3>
-<h3 align="center">
-  Fast in every way that matters
-</h3>
+</p>
+<p align="center">
+  <strong>
+    Fast in every way that matters
+  </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
 </p>
@@ -40,7 +42,7 @@
   </a>
 </p>
 
-<h3 align="center">
+<h2 align="center">
   <a href="https://www.gatsbyjs.com/docs/">Quickstart</a>
   <span> · </span>
   <a href="https://www.gatsbyjs.com/tutorial/">Tutorial</a>
@@ -56,7 +58,7 @@
   Support: <a href="https://twitter.com/AskGatsbyJS">Twitter</a>, <a href="https://github.com/gatsbyjs/gatsby/discussions">Discussions</a>
   <span> & </span>
   <a href="https://gatsby.dev/discord">Discord</a>
-</h3>
+</h2>
 
 Gatsby is a modern web framework for blazing fast websites.
 
@@ -138,6 +140,10 @@ We welcome suggestions for improving our docs. See the [“how to contribute”]
 
 **Start Learning Gatsby: [Follow the Tutorial](https://www.gatsbyjs.com/tutorial/) · [Read the Docs](https://www.gatsbyjs.com/docs/)**
 
+## 🚢 Release Notes
+
+Wondering what we've shipped recently? Check out our [release notes](https://www.gatsbyjs.com/docs/reference/release-notes) for key highlights, performance improvements, new features, and notable bugfixes.
+
 ## 💼 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!
@@ -161,10 +167,7 @@ This repository is a [monorepo](https://trunkbaseddevelopment.com/monorepos/) ma
 
 ### Contributing to Gatsby v2
 
-The maintenance window for Gatsby v2 closes on April 1, 2021.
-
-- During this maintenance window, we will continue to address reported bugs in Gatsby v2.
-- After the maintenance window closes, we will only accept critical security updates for Gatsby v2.
+We are only accepting critical security patches for Gatsby v2.
 
 ## 📝 License
 

docs/docs/debugging-html-builds.md

@@ -2,14 +2,18 @@
 title: Debugging HTML Builds
 ---
 
-Errors while building static HTML files generally happen for one of the following reasons:
-
-1. Some of your code references "browser globals" like `window` or `document`. If
-   this is your problem you should see an error above like "window is not
-   defined". To fix this, find the offending code and either a) check before
-   calling the code if window is defined so the code doesn't run while Gatsby is
-   building (see code sample below) or b) if the code is in the render function
-   of a React.js component, move that code into a [`componentDidMount` lifecycle](https://reactjs.org/docs/react-component.html#componentdidmount) or into a [`useEffect` hook](https://reactjs.org/docs/hooks-reference.html#useeffect), which
+Errors while building static HTML files (The build-time React SSR process) generally happen for one of the following reasons:
+
+1. Some of your code references "browser globals" like `window` or `document`
+   that aren't available in Node.js. If this is your problem you should see an
+   error above like "window is not defined". To fix this, find the offending
+   code and either a) check before calling the code if window is defined so the
+   code doesn't run while Gatsby is building (see code sample below) or b) if
+   the code is in the render function of a React.js component, move that code
+   into a [`componentDidMount`
+   lifecycle](https://reactjs.org/docs/react-component.html#componentdidmount)
+   or into a [`useEffect`
+   hook](https://reactjs.org/docs/hooks-reference.html#useeffect), which
    ensures the code doesn't run unless it's in the browser.
 
 2. Check that each of your JS files listed in your `pages` directory (and any
@@ -22,18 +26,41 @@ Errors while building static HTML files generally happen for one of the followin
    is stricter than v3](/docs/reference/release-notes/migrating-from-v1-to-v2/#convert-to-either-pure-commonjs-or-pure-es6).
    The solution is to only use `import` and this also extends to `gatsby-ssr` and `gatsby-browser` files.
 
-4. Your app is not correctly [hydrated](https://reactjs.org/docs/react-dom.html), which results in gatsby develop and gatsby
-   build being inconsistent. It's possible that a change in a file like `gatsby-ssr` or `gatsby-browser` has a structure that is
-   not reflected in the other file, meaning that there is a mismatch between client and server output.
+4. Your app doesn't correctly
+   [hydrate](https://reactjs.org/docs/react-dom.html) in the client, which
+   results in gatsby develop and gatsby build being inconsistent. It's possible
+   that a change in a file like `gatsby-ssr` or `gatsby-browser` has
+   a structure that is not reflected in the other file, meaning that there is
+   a mismatch between client and server output.
 
 5. Some other reason :-) #1 is the most common reason building static files
    fail. If it's another reason, you have to be a bit more creative in figuring
    out the problem.
 
 ## How to check if `window` is defined
 
+When referencing `window` in a React component.
+
+```jsx
+import * as React from "react"
+
+// Check if window is defined (so if in the browser or in node.js).
+const isBrowser = typeof window !== "undefined"
+
+export default function MyComponent() {
+  let loggedIn = false
+  if (isBrowser) {
+    window.localstorage.getItem("isLoggedIn") === "true"
+  }
+
+  return <div>Am I logged in? {loggedIn}</div>
+}
+```
+
+When requiring a module:
+
 ```javascript
-// Requiring function causes error during builds
+// Requiring a function causes an error during builds
 // as the code tries to reference window
 const module = require("module") // Error
 

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

@@ -89,6 +89,8 @@ The following errors are related to styles in your site, using CSS, preprocessor
 
 ### Inconsistent CSS styles between develop and build using styled-components or emotion
 
+_NOTE: We're in process of adding SSR support to the develop server. To use it now, enable the `DEV_SSR` flag in your gatsby-config.js — https://github.com/gatsbyjs/gatsby/discussions/28138_
+
 A common problem that trips up users that install and begin to use styled-components or emotion is not including the related plugin in the config. Because `gatsby develop` doesn't run server-side rendering, the build may look different if the plugin is not included to tell Gatsby to server-side render the styles for the CSS-in-JS solution being used.
 
 Adding `gatsby-plugin-styled-components` (in the case of styled-components) or `gatsby-plugin-emotion` (in the case of emotion) to `gatsby-config.js` will inform Gatsby to process the styles server-side so they display correctly in the final build.

docs/docs/how-to/previews-deploys-hosting/how-gatsby-works-with-github-pages.md

@@ -18,7 +18,7 @@ You must select which branch will be deployed from your repository settings in G
 
 2. Under the repository name, click Settings.
 
-3. In the GitHub Pages section, use the Source drop-down to select master (for publishing to the root subdomain) or gh-pages (for publishing to a path like `/docs`) as your GitHub Pages publishing source.
+3. In the GitHub Pages section, use the Source drop-down to select `main` (for publishing to the root subdomain) or `gh-pages` (for publishing to a path like `/docs`) as your GitHub Pages publishing source.
 
 4. Click Save.
 
@@ -56,24 +56,24 @@ Then add a `deploy` script to `package.json` in your repository's codebase:
 
 When you run `npm run deploy` all contents of the `public` folder will be moved to your repository's `gh-pages` branch. Make sure that your repository's settings has the `gh-pages` branch set as the source to deploy from.
 
-**Note**: to select master or gh-pages as your publishing source, you must have the branch present in your repository. If you don't have a master or gh-pages branch, you can create them and then return to source settings to change your publishing source.
+**Note**: To select `main` or `gh-pages` as your publishing source, you must have the branch present in your repository. If you don't have a `main` or `gh-pages` branch, you can create them and then return to source settings to change your publishing source.
 
 ### Deploying to a GitHub Pages subdomain at github.io
 
-For a repository named like `username.github.io`, you don't need to specify `pathPrefix` and your website needs to be pushed to the `master` branch.
+For a repository named like `username.github.io`, you don't need to specify `pathPrefix` and your website needs to be pushed to the `main` branch.
 
-> ⚠️ Keep in mind that GitHub Pages forces deployment of user/organization pages to the `master` branch. So if you use `master` for development you need to do one of these:
+> ⚠️ Keep in mind that GitHub Pages forces deployment of user/organization pages to the `main` branch. So if you use `main` for development you need to do one of these:
 >
-> - Change the default branch from `master` to something else, and use `master` as a site deployment directory only:
+> - Change the default branch from `main` to something else, and use `main` as a site deployment directory only:
 >   1. To create a new branch called `source` run this command:
->      `git checkout -b source master`
->   2. Change the default branch in your repository settings ("Branches" menu item) from `master` to `source`
+>      `git checkout -b source main`
+>   2. Change the default branch in your repository settings ("Branches" menu item) from `main` to `source`
 > - Have a separate repository for your source code (so `username.github.io` is used only for deployment and not really for tracking your source code)
 
 ```json:title=package.json
 {
   "scripts": {
-    "deploy": "gatsby build && gh-pages -d public -b master"
+    "deploy": "gatsby build && gh-pages -d public -b main"
   }
 }
 ```
@@ -96,7 +96,7 @@ You can use the [gh-pages npm module](https://www.npmjs.com/package/gh-pages) to
 
 To push changes from the CI system to GitHub, you'll need to authenticate. It's recommended to use [GitHub developer tokens](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line).
 
-In GitHub go to your account settings -> Developer settings -> Personal access tokens, and create a new token that provides the `repo` access permissions.
+In GitHub go to your Account settings -> Developer settings -> Personal access tokens, and create a new token that provides the `repo` access permissions.
 
 In [Travis's settings for the repository](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings), add a new secret environment variable of the name `GH_TOKEN` with the value of the token copied from GitHub. Make sure you **DO NOT toggle the "display in build logs" setting to on** as the token should remain secret. Otherwise, strangers would be able to push to your repository (a big security issue).
 
@@ -131,12 +131,12 @@ deploy:
   script: cd docs/ && yarn install && yarn run deploy
   skip_cleanup: true
   on:
-    branch: master
+    branch: main
 ```
 
 To break-down the important bits here for deploying the Gatsby website from Travis to GitHub Pages:
 
 1. `before_script` is used to install the Gatsby CLI so it can be used in the project's run script to build the Gatsby website
-2. `deploy` will only fire when the build runs on the master branch, in which case it will fire off the deploy script. In the above example, the Gatsby site is located in a `docs/` directory. The script changes into that directory, installs all the website dependencies, and runs the deploy script as was set in the previous step.
+2. `deploy` will only fire when the build runs on the `main` branch, in which case it will fire off the deploy script. In the above example, the Gatsby site is located in a `docs/` directory. The script changes into that directory, installs all the website dependencies, and runs the deploy script as was set in the previous step.
 
 Committing and pushing both the `.travis.yml` and `package.json` files to your base branch will be the final step in the process.