Gatsby Cloud Docs

Getting started with Gatsby Cloud and Sanity.io

Learn how to connect Gatsby Cloud with Sanity

Table of Contents

What are Gatsby Cloud and Sanity, and why use them together?

Sanity.io is a headless CMS that content editors can use to edit and publish content. Gatsby Cloud allows you to integrate your site with Sanity.io in order to run performant builds and preview content changes made in the CMS before publishing.

Setting up a Sanity and Gatsby site

First, you’ll need a Gatsby site that’s connected to a Sanity project and its source code needs to live on GitHub. If you haven’t set that up yet, you can quickly create a new project by selecting one of the Gatsby templates on sanity.io/create.

Best practices for gatsby-config.js settings

Make sure that watchMode and overlayDrafts are set to true in the Sanity plugin options (this is enabled by default in sites from sanity.io/create). With watchMode, Gatsby injects content changes on the fly, without you having to reload the development server, or refresh the browser. This is done via a listener that receives the content changes from Sanity’s real-time backend. In addition, with Sanity, multiple people in the same Sanity studio can make content edits that are instantly reflected on the frontend development server and on Gatsby Preview.

Signing in to Gatsby Cloud

Select Sign in with GitHub. You’ll be asked to authorize the Gatsby Cloud app with your GitHub account. If you need to request access to one or more repositories, you can click “request access” here or later, when creating an instance.

Once signed in, configuring Gatsby Cloud with Sanity requires several steps that are walked through below.

Creating an instance

Once you’ve authenticated with Cloud and GitHub, you can create an instance from the “Create a new Gatsby Cloud site” page.

Use the “I already have a Gatsby site” flow to manually integrate your site.

Add my own site

Pick your Gatsby site from the list of GitHub repositories. You can use the search input to narrow down the list.

Gatsby Cloud Add an instance page

If you don’t see your site, it might be because it belongs to a GitHub organization, rather than your personal account. You can connect a new GitHub Organization.

Note: Repositories must contain one Gatsby project configured at their root to be enabled. Gatsby Cloud works best with Gatsby version 2.20.16 and higher.

Select branch and publish directory

You’ll need to select a branch and then indicate the publish directory where the gatsby-config.js lives. If you leave the field blank, it defaults to the root of the site.

Select branch and directory

Once the branch and base directory are correct, select “Next.”

Create the instance

Integration Step - automatic or manual

If you have already configured an instance of Sanity or if you don’t see Sanity in the “Automatic Provisioning” list, skip to Manual Integration.

If you do see Sanity in the “Automatic Integrations” section, consider using the “Automatic Integration” flow and Gatsby Cloud will set-up your CMS for you!

Automatic Integration

Find Sanity in the automatic integrations section, press “Connect” and follow the set-up instructions to link Sanity with Gatsby Cloud.

Once you’ve authorized Sanity and selected the appropriate organization, press “Create site” which will create your instance.

Manual Integration

First, click “Skip this step” to configure Sanity manually.

Gatsby Cloud will automatically try and detect environment variables necessary in your gatsby-config.js. However — consider adding any additional variables that automatic detection may have missed. See “Setting up Environment Variables” for more info.

Note that you will be able to add, delete, or update these later on in “Site Settings”.

Once you’ve added the necessary environment variables, you can press “Create site” which will create your instance in Gatsby Cloud!

Site is Created

After following the “Automatic Integration” or “Manual Integration” flow you now have an instance of Gatsby Cloud configured with environment variables and a provided Gatsby Preview instance you can share with your team. Woo-hoo!

Setting up Environment Variables

An environment variable references a value that can affect how running processes will behave on a computer, for example in staging and production environments. You must save environment variables in Gatsby Cloud to authorize your instance to pull source data from Sanity.

You will need to add into Gatsby Cloud any environment variable required for your app to run, such as deployment or test environment configuration settings.

You will also need to add in the following Gatsby Cloud-specific environment variables:

Set an environment variable called SANITY_READ_TOKEN and its value is the token you generate from https://manage.sanity.io/projects/<YourProjectId>/settings/api

  1. Create a token (Manage -> Settings -> API), and Add New Token. You can double check gatsby-config.js and the plugin entry for gatsby-source-plugin for the variable name. If you find process.env.SANITY_TOKEN you should enter the variable in Gatsby Cloud’s configuration as SANITY_TOKEN.

Select Next

Click Next and wait for the first instance to be generated. Now, when you change any copy or content in Sanity, Gatsby Cloud should be up to date with your changes.

Setup Gatsby Preview widget in Sanity Studio dashboard

Follow the steps in this doc to add the Gatsby Cloud widget to the Sanity Studio dashboard. This makes it much easier for content editors to access the preview instance.

Setting up a local dev environment

If you’d also like to develop your site locally, add the SANITY_TOKEN to the .env file.

Create a file called .env in the web folder:

~/PATH_TO_PROJECT/web
cp .env-example .env

Next, create a read token. Go to https://manage.sanity.io/projects/<YourProjectId>/settings/api (Manage -> Settings -> API), and Add New Token. Give it a nice descriptive label, and only read rights. Copy this token to the .env file as SANITY_TOKEN=”TOKEN”

If you use one of the templates from sanity.io/create, you can add a token with read rights to the /web/.env.development.template file and rename it to .env.development to make it work on local development. The env files with your token should not be committed to git.

To load the token into Gatsby, you’ll need to restart the local development server again.

The Gatsby Newsletter

Keep up with the latest things Gatsby!
Loading...

Product

Why Gatsby?How It WorksIntegrationsDocumentationPricingStatus

How It Works

Bring Data From AnywhereWrite Modern AppsUnreal PerformanceOne-Click DeploymentAll Guides
Terms of UsePrivacy Policy
© 2020 Gatsby, Inc.