Tutorial | Draft Preview with Netlify

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, the easiest is through the Status system field. We will be using the Status field for the guide.

The stack we will be using for this example is:

Why use 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

1. Setting up your .env files

The website will use PATs for the GraphQL queries. Now any content served, will be pre-filtered 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 the file. Add this file into your .gitignore to prevent committing sensitive information. This is a good time to also add an .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"

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

2. Correlating build commands to a specific Permanent Authorization Token

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.

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

3. Refactoring your gatsby-config.js

Allow your config file to variably receive data depending on 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}`,
        },
    },
  },
]

4. 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.

Now when your content editor creates a new draft content entry, you can build a branch (make sure your Netlify settings deploy all branches for this to work) and send the deploy link. Drafted content will now be visible for them to make changes as needed.

Are you ready?

Join our community of passionate developers!