Adding a Staging Environment to my Sanity + Gatsby Experience with Netlify

👋, Back at it again with another Headless + Preview experience using our favorite tools here at The Couch. This time instead of using Next.js for my Gatsby preview I decided that the build pipeline for the site was actually fast enough to just create a second environment within Netlify itself. This is a relatively easy task but I figured I’d walk you through how we did it anyway.

Part 1 — Netlify Setup

I’m assuming you’re using Netlify in this case. We have a Github integration that automatically builds from deployments to a Master branch. In order to add another deployment type we have to toggle the default Deploy settings. You’ll want to navigate to your project and go into Settings->Build & Deploy. From there scroll down to Deploy contexts and hit Edit Settings. We’re going to want to add a Branch Deploy in this case:

Add an additional Branch called `staging` or whatever you’re using

From there we’re going to scroll down to the build hooks. You should already have a build hook set up for the Master branch. Add a new hook and set it to the Staging branch:

Select your secondary branch for staging deployments

Part 2 — Sanity

Login to manage.sanity.io and select the project you’re working on. Select Settings->API from the dashboard. Scroll down to the bottom and add the new webhook URL that you just set up in Netlify:

Additionally in our Sanity schema we’re going to want to add a new field to our page/post types that we’ll be using to toggle the Staging and Production environments:

{
    name: 'environment',
    title: 'Environment',
    type: 'string',
    options: {
       list: [
          {title: 'Production', value: 'production'},
          {title: 'Staging', value: 'staging'},
       ],
    layout: 'dropdown'
    }
},

You’ll want to deploy this code so it’s accessible to the client in production.

Part 3 — Gatsby/Data

This last part is actually a little different in my use case. This is because I write my own GraphQL source plugins when working with external CMS solutions and Gatsby. However with the new API I will hopefully in the future not have to do this thanks to the New Schema Customizations. However I built this site prior to this improvement being implemented in 2.2.0.

As a result I query custom with my own Source plugin. First let’s set up a netlify.toml if you don’t have one already in the root of your project.

[context.production]
   environment = { TYPE = 'production' }
[context.staging]
   environment = { TYPE = 'staging' }

We’ll use this new TYPE to access the production vs staging content in our deploys.

Lastly I’ve modified my GROQ query in my custom source plugin to pass in the above variable (which you can test in Sanity Vision as well):

const queryPages = `*[_type == "page" && (environment == 'production' || environment == '${process.env.TYPE}')] {
    ...,
}

As you can see with the above query we’re fetching all the documents labeled production as we’ll want to make sure the staging environment has the same content as production, but additionally fetching environment again in the event that the branch is the staging one it’ll also fetch the staging documents.

We’ve now got deployments happening both from the master branch and staging branch every time content is saved in Sanity. This will allow the client to see updates in both environments in around ~2 minutes. While this isn’t instant it’s still pretty good while Gatsby preview is still in beta :).

~Cheers