Sanity.io is a headless CMS that content editors can use to edit and publish content. Gatsby Preview allows developers and content editors to preview code and content changes made in their CMS before publishing those changes.
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.
Make sure that
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.
Sign in with GitHub. You’ll be asked to authorize the Gatsby Preview 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 a preview instance.
Once signed in, configuring Gatsby Preview with Sanity requires several steps that are walked through below.
Once you’ve authenticated with Preview and GitHub, you can create a preview instance from the “Create a new Preview instance” page.
We’ll be using the “Add my own site” flow to manually integrate our site.
Select your organization from the dropdown menu and then select your site using the search bar or from the list. Consider using the “Search your Github repositories” searchbar to narrow down your sites.
Preview will list each organization that you have permission for in a dropdown, allowing you to work with more than one organization’s repositories.
Note: Repositories must contain one Gatsby project configured at their root to be enabled. Gatsby Preview works best with Gatsby version 2.1.0 and higher.
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 “Next” once you’ve filled in the branch and publish directory—or if the defaults are good to go!
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!
Find Sanity in the automatic integrations section, press “Connect” and follow the set-up instructions to link Sanity with Gatsby Cloud.
As an example, consider the following example using Contentful:
Finally, press “Create Preview Site” which will create your instance of Gatsby Preview.
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 ones or variables that our automatic detection may have missed. See “Setting up Environment Variables” for more info.
Once you’ve added the necessary environment variables, you can press “Create Preview Site” which will create your instance of Gatsby Preview!
After following the “Automatic Integration” or “Manual Integration” flow you now have an instance of Gatsby Cloud configured with environment variables and an provided Gatsby Preview instance you can share with your team. Woo-hoo!
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 Preview to authorize your preview instance to pull source data from Cosmic JS.
You will need to add into Gatsby Preview 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 Preview-specific environment variables:
Cosmic JS buckets typically have a bucket slug/id as well as a “read key,” both of which can be found Settings -> Basic Settings from the Cosmic JS sidebar.
You will want to grab these values and add them to your Gatsby Preview instance. A typical naming convention will look like:
|The bucket slug (or bucket id) for the Cosmic JS instance|
|The read key for your Cosmic bucket|
Next and wait for the first preview instance to be generated. Now, when you change any copy or content in Cosmic JS, Gatsby Preview should be up to date with your changes.
Follow the steps in this doc to add the Gatsby Preview widget to the Sanity Studio dashboard. This makes it much easier for content editors to access the preview instance.
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
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.