gatsbyjs · Aug 25, 2022 · Aug 25, 2022 · Aug 25, 2022 · Aug 25, 2022 · Aug 26, 2022
Showing 416 changed files with 7,390 additions and 17,967 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -169,7 +169,7 @@ commands:
                 command: "REACT_VERSION=<< parameters.react_version >> TEST_PATH=<< parameters.test_path >> node ./scripts/upgrade-react"
       - run:
           name: Install gatsby-dev@next
-          command: yarn global add gatsby-dev-cli@next
+          command: yarn global add gatsby-dev-cli@next --ignore-engines
       - run:
           name: Run tests (using defaults)
           command: ./scripts/e2e-test.sh "<< parameters.test_path >>" "<< parameters.test_command >>"
@@ -280,7 +280,9 @@ jobs:
           test_path: integration-tests/gatsby-pipeline
 
   integration_tests_gatsby_cli:
-    executor: node
+    executor:
+      name: node
+      image: "14.16.0"
     steps:
       - e2e-test:
           test_path: integration-tests/gatsby-cli

diff --git a/docs/docs/glossary/wpgraphql.md b/docs/docs/glossary/wpgraphql.md
@@ -34,31 +34,30 @@ Then you can configure Gatsby to work with your new endpoint.
 
 ### Using WPGraphQL with Gatsby
 
+We recommend using the official [gatsby-source-wordpress](/plugins/gatsby-source-wordpress/) plugin, which sources data from the WPGraphQL plugin.
+
 You'll need to do two more things before you can use your WordPress-backed GraphQL server with Gatsby:
 
-1. install the [gatsby-source-graphql](/docs/third-party-graphql/) plugin; and
-2. update `gatsby-config.js`.
+1. Install the [gatsby-source-wordpress](/plugins/gatsby-source-wordpress/) plugin; and
+2. Update `gatsby-config.js`.
 
-Use [npm](/docs/glossary#npm) to install [gatsby-source-graphql](/docs/third-party-graphql/).
+Use [npm](/docs/glossary#npm) to install [gatsby-source-wordpress](/plugins/gatsby-source-wordpress/).
 
 ```shell
-npm install gatsby-source-graphql
+npm install gatsby-source-wordpress
 ```
 
-Then update `gatsby-config.js`. Add the plugin to your Gatsby instance. Specify the URL of the GraphQL endpoint and set other [configuration options](/plugins/gatsby-source-graphql/).
+Then update `gatsby-config.js`. Specify the URL of the WPGraphQL endpoint and set other [configuration options](/plugins/gatsby-source-wordpress/).
 
 ```javascript
 module.exports = {
   plugins: [
     {
-      resolve: "gatsby-source-graphql",
+      resolve: "gatsby-source-wordpress",
       options: {
-        // Remote schema query type. This is an arbitrary name.
-        typeName: "WPGraphQL",
-        // Field name under which it will be available. Used in your Gatsby query. This is also an arbitrary name.
-        fieldName: "wpcontent",
-        // GraphQL endpoint, relative to your WordPress home URL.
-        url: "https://example.com/blog/graphql",
+        url:
+          process.env.WPGRAPHQL_URL ||
+          `https://path-to-your-wordpress-instance.com/graphql`,
       },
     },
   ],

diff --git a/docs/docs/how-to/cloud/create-a-deploy-to-gatsby-cloud-button.md b/docs/docs/how-to/cloud/create-a-deploy-to-gatsby-cloud-button.md
@@ -0,0 +1,36 @@
+---
+title: "Create a Deploy to Gatsby Cloud Button"
+description: "Learn how to add a deploy button to your Github repository"
+---
+
+Gatsby Cloud supports Deploy Buttons which you can use to quickly create new sites from Github repositories.
+
+[![Deploy to Gatsby Cloud](https://www.gatsbyjs.com/deploynow.svg)](https://www.gatsbyjs.com/dashboard/deploynow?url=https://github.com/gatsbyjs/gatsby-starter-blog)
+
+At this time, only public Github repos are supported.
+
+Have a feature request for Deploy Buttons? [Suggest a feature](https://gatsby.canny.io/gatsby-cloud).
+
+### Configure a button
+
+Set the `url` parameter of the link to your public Github repo.
+
+HTML snippet:
+
+```html
+<a
+  href="https://www.gatsbyjs.com/dashboard/deploynow?url=https://github.com/gatsbyjs/gatsby-starter-blog"
+  target="_blank"
+>
+  <img
+    src="https://www.gatsbyjs.com/deploynow.svg"
+    alt="Deploy to Gatsby Cloud"
+  />
+</a>
+```
+
+Markdown:
+
+```markdown
+[![Deploy to Gatsby Cloud](https://www.gatsbyjs.com/deploynow.svg)](https://www.gatsbyjs.com/dashboard/deploynow?url=https://github.com/gatsbyjs/gatsby-starter-blog)
+```
diff --git a/docs/docs/how-to/cloud/create-site-from-repository.md b/docs/docs/how-to/cloud/create-site-from-repository.md
@@ -0,0 +1,73 @@
+---
+title: "Create a Site from a Repository"
+description: "Learn how to create a Gatsby Cloud site from a repository"
+---
+
+## Introduction
+
+Gatsby Cloud allows you to create a site by importing your Gatsby project from a Git repository. This guide provides the steps for importing a repository from your Git provider and building that site on Gatsby Cloud.
+
+## Prerequisites
+
+You can use the [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog) as a starting point. Select **"Use this template"** to create a new repository using the starter as a template.
+
+![Button to create a new repository from a starter](../../images/use-this-template.png)
+
+## Directions
+
+### 1. Select a Git provider
+
+From your Gatsby Cloud dashboard, click **"Add a Site"**.
+
+![Button to add a site from the Gatsby Cloud dashboard](../../images/add-site.png)
+
+In the "Import from a Git repository" section, choose your Git provider and install the Gatsby Cloud app. For the sake of this article you'll use Github, however GitLab and BitBucket are also supported.
+
+![List of Git Providers](../../images/import-from-repo.png)
+
+### 2. Specify repository details
+
+Once connected to your Git provider, find the repository you would like to add to Gatsby Cloud and click **"Import"**. You can then provide the details for your site:
+
+1. The site name (defaults to `<repo name>-<branch name>`).
+1. The branch to import from and set as your "Production branch" in Gatsby Cloud (in this case, the `main` branch).
+1. The base directory, i.e., the directory containing the Gatsby site (the root directory, `/`, is default).
+
+![Basic site configuration](../../images/basic-configuration.png)
+
+After you enter the site details, click **"Next"**.
+
+### 3. Add optional integrations
+
+Next, you will be prompted to connect an optional content management system (CMS) to your site. This step will vary depending on the CMS provider, so there are [separate tutorials](https://support.gatsbyjs.com/hc/en-us/articles/1500000746742) for each supported CMS. However, for this specific example, you can scroll past this card to continue on.
+
+![No Supported Integrations Found](../../images/no-integrations.png)
+
+### 4. Configure environment variables
+
+Now, you will be asked to [set up environment variables](/docs/reference/cloud/managing-environment-variables) for your site. The "Default" starter does not use any environment variables so you will skip this step as well. Click **"Build Site"** to continue.
+
+![Section to add environment variables to a new Gatbsy Cloud site](../../images/no-environment-variables.png)
+
+### 5. Finish
+
+Once your site is done building, you can view the site in two places:
+
+#### Private build URL
+
+Use the build URL to preview the deployed site. This URL is not indexed and is only accessible via direct link.
+
+![Gatsby Cloud Private Build URL link](../../images/private-build-link.png)
+
+#### Public default domain
+
+Use your Gatsby Hosting provided "default domain" to access the public deployment of your site. Gatsby Hosting is turned on by default and the "default domain" is listed under "Site Settings > Hosting".
+
+![Gatsby Cloud default hosting domain](../../images/default-domain.png)
+
+### Troubleshooting
+
+When creating a site from a Github repository, you'll be asked to authenticate with Github. In instances where you're having trouble authenticating and importing your site:
+
+1. Log out and log back in. If you are still aren't able to import the site, your Github repository is part of a Github organization, and you are not an owner of that organization, then you may not have sufficient permission to install the Gatsby Cloud app to Github.
+1. When you try to import your repository to Gatsby Cloud, an email is sent to the owner(s) of that organization to authorize Gatsby Cloud. Once they authorize via the link in that email, then you will be able to import your repository into Gatsby Cloud.
diff --git a/docs/docs/how-to/cloud/create-site-from-template.md b/docs/docs/how-to/cloud/create-site-from-template.md
@@ -0,0 +1,66 @@
+---
+title: "Create a Site from a Template"
+description: "Learn how to create a Gatsby Cloud site from a template"
+---
+
+## Introduction
+
+This guide covers how to create a Gatsby Cloud site by cloning a Gatsby starter. Note, cloning of starters is only supported for Github. If you use GitLab or BitBucket, you'll have to follow the [Create a Site from a Repository](/docs/how-to/cloud/create-site-from-repository/) guide instead.
+
+## Directions
+
+### 1. Choose your starter template
+
+From your Gatsby Cloud dashboard, click **"Add a Site"**.
+
+![Button to add a site from the Gatsby Cloud dashboard](../../images/add-site.png)
+
+On the right hand side, click on the card labeled "Gatsby Default Starter".
+
+![Clone Gatsby Default Starter](../../images/default-starter.png)
+
+### 2. Configure your repository
+
+The first time you set up a Gatsby Cloud site, you will need to connect your Gatsby account to Github by clicking on the "Github" icon in the "Create a Git repository" card.
+
+![Create a Git Repository](../../images/create-git-repo.png)
+
+Next, a pop up window should appear and prompt you to install the Gatsby Cloud app to your Github personal account. Click **"Install"**.
+
+![Gatsby Cloud app permissions](../../images/install-gatsby-cloud-app.png)
+
+After the Github app is installed, you will return to Gatsby Cloud. Here you can select a different Github organization to host the repository under as well as change the name of the repository that will be created if you prefer. Then click **"Next"** to create the site.
+
+![Configure Git repository settings](../../images/configure-repository.png)
+
+### 3. Connect integrations
+
+Next, you'll be prompted to connect any integrations. Here is where you can connect your Gatsby Cloud site to your CMS instance. For the purposes of this tutorial, you can select **"Skip this step"**.
+
+![List of available integrations](../../images/connect-integrations.png)
+
+### 4. Set-up summary
+
+After the repository is created, you'll be given the option to configure any necessary environment variables. This step allows you to add both build and preview variables to your site.
+
+![Section to add environment variables](../../images/setup-summary.png)
+
+Next, click **"Create Site"** and you will be taken to the main tab of the Site Overview page for your new site.
+
+![Site Overview screen](../../images/site-overview.png)
+
+### 5. Finish
+
+Once your site is done building, you can view the site in two places:
+
+#### Private build URL
+
+Use the build URL to preview the deployed site. This URL is not indexed and is only accessible via direct link.
+
+![Private Build URL Link](../../images/private-build-link.png)
+
+#### Public default domain
+
+Use your Gatsby Hosting provided "default domain" to access the public deployment of your site. Gatsby Hosting is turned on by default and the "default domain" is listed under "Site Settings > Hosting".
+
+![Default Domain URL link](../../images/default-domain-link.png)
diff --git a/docs/docs/how-to/cloud/deploying-functions-on-gatsby-cloud.md b/docs/docs/how-to/cloud/deploying-functions-on-gatsby-cloud.md
@@ -0,0 +1,68 @@
+---
+title: "Deploying Functions on Gatsby Cloud"
+description: "Learn how to deploy Gatsby Serverless Functions on Gatsby Cloud"
+---
+
+## Introduction
+
+The Gatsby framework now supports general access to serverless functions in local development as well as in Gatsby Cloud. These [express](https://expressjs.com/)-style functions allow Gatsby developers to build out secure, scalable APIs alongside their Gatsby projects.
+
+### Prerequisites
+
+Functions are a Gatsby core feature and are not specific to Gatsby Cloud. To learn more about how to implement functions in the Gatsby framework, check out the [Reference guide](/docs/reference/functions/).
+
+### Routing in Gatsby Cloud
+
+Functions that are included in a Gatsby project and deployed on Gatsby cloud are available at any build URL. This includes any preview URLs (`gstb.io` domain) or hosting URLs (`gatsbyjs.io` or your custom domain).
+
+```javascript:title=src/api/hello-world.js
+const sample = (req, res) => {
+    res.status(200).json({"message": "Hello, World!"})
+};
+
+export default sample;
+```
+
+### Environment variables
+
+Functions will have access to any environment variables that you’ve added to either the production or preview environments in Gatsby Cloud.
+
+![Gatsby Cloud environment variables settings](../../images/env_vars.png)
+
+```javascript:title=src/api/hello-world.js
+const sample = (req, res) => {
+  let key = process.env.SAMPLE_VAR;
+  //run code that uses key
+
+  res.status(200).json({ message: "Hello, World!" });
+};
+
+export default sample;
+```
+
+### Setting cache headers for functions
+
+Users can set custom headers to control cache settings to ensure that function invocations are appropriately handled when served to [CDN](/docs/glossary/content-delivery-network/) users. Any cache-header setting that users add to their function will be passed through and respected on the CDN:
+
+```javascript:title=src/api/hello-world.js
+const sample = (req, res) => {
+  res.setHeader(`Cache-Control`, `public, max-age=60`);
+  res.status(200).json({ message: "Hello, World!" });
+};
+
+export default sample;
+```
+
+### Accessing logs for functions
+
+You can access function logs by viewing the build details for the CMS Preview, Pull Request Build, or Production build. See the [Build Logs](/docs/reference/cloud/build-logs) article for more information on accessing build details.
+
+![Gatsby Cloud Function Invocations Log](../../images/function-invocation-log.png)
+
+### Tracking invocation counts
+
+Like the bandwidth and request tracking in Gatsby Cloud, users can track their invocation count across all their Gatsby sites on any workspace landing page as well as site-specific usage on any site page.
+
+Additionally, users can view function-specific invocation counts in the function logs of the build details for any build that implements that function. See the [Platform Limits](/docs/reference/cloud/platform-limits) article for information on function invocation limits.
+
+![Invocations Count on the Gatsby Cloud dashboard](../../images/function-invocation-count.png)
diff --git a/docs/docs/how-to/cloud/deploying-to-firebase.md b/docs/docs/how-to/cloud/deploying-to-firebase.md
@@ -0,0 +1,65 @@
+---
+title: "Deploying to Firebase on Gatsby Cloud"
+description: "Learn how to deploy your Gatsby Cloud site to Firebase"
+---
+
+## Introduction
+
+Gatsby Cloud is a performant platform for building your Gatsby site. Even better, it integrates with Content Delivery Networks (CDNs) like [Firebase](https://firebase.google.com/) so you can build and deploy your site seamlessly.
+
+## Prerequisites
+
+This guide assumes you already:
+
+- Have a Firebase account.
+- Have a Gatsby Cloud site created.
+
+You can use either of the following site creation options if you don't have one already:
+
+- [Create a Site from a Template](/docs/how-to/cloud/create-site-from-template)
+- [Create a Site from a Repository](/docs/how-to/cloud/create-site-from-repository)
+
+## Setting up a hosting integration
+
+Once your site is available inside Gatsby Cloud, navigate to the "Site Settings" tab.
+
+Inside "Site Settings," select **"Hosting > Hosting integrations."** Here you'll see Firebase listed among the other available hosting providers.
+
+![Select Firebase from hosting integrations](../../images/firebase-hosting.png)
+
+Click **“Connect”** to the right of the Firebase logo, and you’ll be prompted to login into your Firebase account. If you don’t have one, you can create one now.
+
+Once you’re authenticated with Firebase, you’ll be prompted to authorize Gatsby Cloud to interact with Firebase on your behalf. After you’ve completed this step, you’re ready to configure deployment in Gatsby Cloud.
+
+### Connect with a Firebase project
+
+If you don’t already have one, create a Firebase project in your [Firebase console](https://console.firebase.google.com/).
+
+On the “Firebase Integration” screen choose a Firebase project for deployment from the dropdown. Note that you can enter a Firebase site name for projects with multiple sites.
+
+### Configuration with Firebase
+
+Firebase allows you to configure customized hosting behavior such as redirects, headers, cache settings, and which files to deploy. You can define these behaviors in a `firebase.json` file. See [Deploying to Firebase](/docs/how-to/previews-deploys-hosting/deploying-to-firebase/) for the Gatsby recommended caching settings.
+
+In order for Gatsby Cloud to use these settings for your Firebase hosting, you’ll need to make sure that your `firebase.json` file ends up in your `/public` directory when your build is complete.
+
+One way you can accomplish this is by adding the following code to your `gatsby-node.js` file:
+
+```javascript:title=gatsby-node.js
+const fs = require("fs");
+exports.onPostBuild = () => {
+  fs.copyFile(`./firebase.json`, `./public/firebase.json`, (err) => {
+    if (err) {
+      throw err;
+    }
+  });
+};
+```
+
+Please see the [Firebase Hosting Configuration](https://firebase.google.com/docs/hosting/full-config) documentation for more deployment customization options.
+
+## Finishing Up
+
+And that’s it! Your site is now set up to build and deploy. Gatsby Cloud will handle everything for you. However, if you want to make a change to your domain, you’ll want to do that directly on the Firebase dashboard.
+
+Note that you can only have one hosting integration. If you choose to configure another provider, that will override your existing Firebase integration.