What is a preview environment flow?

A preview environment flow allows draft or not shown content to be shown under work-in-progress circumstances. Although there are many ways to determine if content is published or in draft, is through the Status system field. We will be using the Status field for the guide.

TL;DR - We will be using Permanent Auth Tokens and Netlify build commands to make branch deploys and local builds, also show draft content.

The stack we will be using for this example is:

Why us a Preview Environment Flow?

Content editors like to view how the writing fits on the page, how images should break up the writing and so on.

At GraphCMS, our content editors are no different. Our website + blog is built using the static website generator, GatsbyJS. We’ve created an in-house solution for this need, and wanted to share how we do it, with you!

In this tutorial, we will assume you already have a Gatsby blog set up and connected to GraphCMS. Here is an example, if that is not the case but you'd like to follow along.

Setting up a preview environment flow

We will break this up into the main files where changes need to be made:

  1. .env and .env.local
  2. package.json & netlify.toml
  3. gatsby-config.js
  4. Configure your build in Netlify

Setting up your .env files

The website will use PATs for GraphQL queries. Now any content served, will be prefiltered by the PAT. When you want to use the website locally, you need a .env.local file in the root of the repository.

Perm Auth Tokens

Create an .env.local file at the root of your project. Copy the corresponding tokens that were created in working with pats into the file. Add this file into your .gitignore to prevent committing sensitive information. This is a good time to also add a .env file with instructions into the root of your project that will prompt new developers joining the project.

# Please create a .env.local file on your machine
# The content of this should be similar to the following replacing XXX with your token

# production token
GRAPHCMS_TOKEN="XXX"

# development token
GRAPHCMS_TOKEN="XXX"

Make sure that you put the .env.local file in .gitignore to not share your sensitive authorization accidentally. Amongst teams, adding the file contents to something like a 1Password vault is a great option.

Correlating build commands to a specific PAT

Now we will add new build commands for Netlify in the package.json. They will be utilized by the netlify.toml file and use the wanted token for different build scenarios.

The build scenarios we've defined for the Preview Environment Flow are:

  • Production Deploy ⇛ Prod Token that filters for status: PUBLISHED
  • Branch Deploy ⇛ Development Token that doesn't filter.
  • PR Preview ⇛ Development Token that doesn't filter.

Here is what should be added into your package.json:

// package.json

	"scripts": {
		"build:netlify:prod": "bash ./scripts/prod-netlify.sh && export GATSBY_BRANCH=${BRANCH} && gatsby build",
		"build:netlify:dev": "bash ./scripts/dev-netlify.sh && export GATSBY_BRANCH=${BRANCH} && gatsby build"
	},

Create a netlify.toml file at the root of your project. Copy and paste the following code.

[context.production]
  command = "yarn build:netlify:prod"
[context.deploy-preview]
  command = "yarn build:netlify:dev"
[context.branch-deploy]
  command = "yarn build:netlify:dev"

Refactoring your gatsby-config.js

Allow your config file to variably receive data depending on the appropriate token in .env.local file.

You'll need to require the env file and specify where its located.

Then you'll use the headers section of the gatsby-source-graphql plugin by passing in the bearer token.

// gatsby-config.js

require('dotenv').config({
    path: `.env.local`,
})

plugins: [
  {
    resolve: "gatsby-source-graphql",
        options: {
        // The top level query type, can be anything you want!
        typeName: "GCMS",
        // The field you'll query against, can also be anything you want.
        fieldName: "gcms",
        // Your API endpoint, available from the dashboard and settings window.
        url: "https://api-euwest.graphcms.com/v1/cjrt5dli1db6q01ggu584vwud/master",
        headers: {
          // Learn about environment variables: https://gatsby.dev/env-vars
          Authorization: `Bearer ${process.env.GRAPHCMS_TOKEN}`,
        },
    },
  },
]

Configure Netlify build

You'll need to navigate to Netlify build environment settings found at https://app.netlify.com/sites/[YOURSITE]/settings/deploys#environment.

Then add the production and development tokens from your .env.local file.

'Netlify Build Environment Variables'

Using a preview environment flow

Now navigating to a branch preview deploy URL (from a GitHub PR or Netlify deploy log) will show you all content including content entries with draft status.

You can also access this development build that shows content entries with draft status by using the yarn develop command.