Skip to main content

Connecting to Prismic

Laura
  • Updated

What is Gatsby Cloud?

Gatsby Cloud is Gatsby's platform for building, serving, and previewing your Gatsby project. To help explain how Gatsby Cloud fits into a project's stack, each of Gatsby Cloud's features can be compared to other common services:

  • Hosting: Serves your site to your visitors. Gatsby Cloud Hosting is like Netlify, Vercel, or Amazon S3.
  • Build: A continuous integration service to build your site on content changes. Gatsby Cloud Builds is like Netlify Build.
  • Preview: A staging site to preview your draft documents before you publish. Gatsby Cloud Previews are like Prismic Previews.
  • Functions: Serves your site's API routes if included in the project. Gatsby Cloud Functions is like Netlify Functions.

Gatsby Cloud integrates with Prismic by allowing you to preview content changes before publishing. When the content changes are published, Gatsby Cloud will rebuild your site with the changes.

Goals of this guide

After completing this guide, you will be able to preview content changes by…

  1. Save and publish content changes to a specific Release in Prismic.
  2. Gatsby Cloud updates a preview version of your site.
  3. Click the Preview button in Prismic to open the preview site.

When the changes are ready to be published, you can deploy your changes by…

  1. Save and publish content changes for a document in Prismic.
  2. Gatsby Cloud rebuilds the site.
  3. The site is deployed with the new content.

1. Set up your Prismic repository

Complete the following steps in your Prismic repository.

Create a Release

  1. Open your Prismic Dashboard and select your repository.
  2. At the top of the page, click the Planned tab.
  3. Create a new Release named "Gatsby Cloud Preview".
  4. Optional: Add or edit documents and save to the newly created Release (learn how to save to a Release).
 

Find and save the Release ID for later

The Release's ID will be needed to setup Gatsby Cloud later in the guide.

You can find the Release ID in the API Browser of your repository. Go to the following URL, but replace your-repository-name with the name of your repository:

https://your-repository-name.prismic.io/api/v2

✅ If you receive a pop-up asking for access, accept it.

After accepting, you will be redirected to the API Browser.

Click the unlock icon and select the corresponding ref ID for the Gatsby Cloud Preview Release.

a03c4985-c199-429d-a5cc-b089727708e9_Dec-08-2020%2B18-03-36.gif.webp

Create API tokens

Next, generate an access token. In this case, you'll need two tokens: one for builds and one for previews.

  • Builds: After generating the first token, you should see the Access to master token. You'll use this token for the Gatsby Cloud Builds server:image.png
  • Previews: Now, create a new token below. Select Access to Master + Releases and then click Add a token. You'll use this token for the Gatsby Cloud Preview server.image.png

These tokens need to be set in one of two places:

  • In the Environment variables in the settings of your Gatsby Cloud Dashboard.
  • Or, if you prefer, you can create an .env file in your project's root and add them there. The variables will be consumed from the source plugin settings from the gatsby-config.js file. If you set it up like this, Gatsby Cloud will automatically read these values when you set up your site.

We'll guide you through configuring these variables in Gatsby Cloud further below in this article. You can learn more about managing environment variables in Gatsby's documentation.

2. Set up your project code

Complete the following steps in your Gatsby project's code.

Install the plugins

Install the required plugins to build and preview your site. Follow the main installation guides for each one:

When setting up gatsby-plugin-prismic-previews, you can stop after the "Add a preview resolver page" step.

Push your project to Github

Sign up or log in to GitHub and push your project to a new repository. We'll use this repository for the Gatsby Cloud integration.

3. Set up Gatsby Cloud

The following steps will take place on Gatsby Cloud.

Configure Gatsby Cloud

Sign in to Gatsby Cloud using the Log in with GitHub option. 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 now or later when creating an instance.

Add a site

Once signed in, follow the next steps:

💡 Repositories must contain one Gatsby project

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.

  1. Import from a Git repository: Once you’ve logged in, click +Add a site and select Import from a Git repository.
  2. Select Git as the provider.
  3. Pick your Gatsby site from your list of GitHub repositories. Then select the branch where you pushed your project. This is usually named master or main. Click Next.
  4. Click Skip this step to configure Prismic manually.
  5. Click Create site. It will create your instance in Gatsby Cloud!

💡 If you don’t see your site

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 to a new GitHub organization.

 

Add environment variables

Environment variables are used in Gatsby Cloud to authorize your site when pulling content from Prismic.

Gatsby Cloud will automatically detect your environment variables in your gatsby-config.js. However, consider adding any additional variables that automatic detection may have missed.

To edit your site's environment variables on Gatsby Cloud, navigate to the following page:

  1. Open your site's Dashboard
  2. Select the Site Settings tab under your site's name
  3. In the sidebar under General, navigate to Environment variables

Once there, add the following variables.

Under the Build variables tab:

  • PRISMIC_REPO_NAME: Your repository name.
  • PRISMIC_API_KEY: The token you set up in your Prismic repository for builds.

Under the Preview variables tab:

  • PRISMIC_REPO_NAME: Your repository name.
  • PRISMIC_API_KEY: The token you set up in your Prismic repository for previews.
  • PRISMIC_RELEASE_ID: The Release ID you previously saved. 

4. Set up webhooks

Webhooks are used to automatically notify Gatsby Cloud when the content in Prismic changes.

Webhook for previews

In your Gatsby Cloud site dashboard, navigate to the Site Settings tab.

Scroll down to Preview Webhook and copy the URL listed in the box.image.png

Next, add the webhook to your Prismic repository.

  1. In your Prismic repository, navigate to Settings Webhooks.
  2. Click the Create a webhook button.
  3. Name the webhook "Gatsby Cloud Preview".
  4. Paste the Preview webhook URL copied from Gatsby Cloud into the URL field.
  5. Ensure all checkboxes under Triggers Releases are checked.
  6. Click the Add this webhook button.
 

Webhook for Builds

Back in your Gatsby Cloud site dashboard, navigate to the Site Settings tab.

Scroll down to Builds Webhook and copy the URL listed in the box.image.png

Next, add the webhook to your Prismic repository. The process is the same as the webhook for previews but with a different URL.

  1. In your Prismic repository, navigate to Settings Webhooks.
  2. Click the Create a webhook button.
  3. Name the webhook "Gatsby Cloud Builds".
  4. Paste the Builds webhook URL copied from Gatsby Cloud into the URL field.
  5. Ensure all checkboxes under Triggers Releases are unchecked.
  6. Click the Add this webhook button.

Now the production build will automatically update when changes are published in Prismic.

5. Enable previews in your repository

Navigate to your Gatsby Cloud dashboard. On the far right, adjacent to the Site Settings tab, select the CMS Preview tab.

Copy the URL that appears in the middle of the page (it should start with "preview-").image.png

Next, setup your Prismic repository for the Preview URL.

  1. In your Prismic repository, navigate to Settings and select Previews in the sidebar.
  2. Click the Create a Preview button.

Fill out the form with the following values:

  • Site Name: "Gatsby Cloud Preview"
  • Domain for your application: Paste the CMS Preview URL copied from Gatsby Cloud.
  • Link Resolver: /preview
    If you used a different preview resolver URL while setting up gatsby-plugin-prismic-preview, use that URL instead.

image.png

6. Wrap up

At this point, Gatsby Cloud and your Prismic repository are fully setup. To wrap up, you have completed the following as part of this guide:

  • You have correctly configured your Gatsby Cloud integration.
  • You've set up all the necessary environment variables for Gatsby Cloud.
  • You have a dedicated Prismic Release to preview your pages.

Gatsby Cloud is now configured to automatically rebuild your site when content is published in Prismic. You can also preview content before publishing and share the preview URL using Gatsby Cloud's preview feature.

Related articles

Comments

0 comments

Please sign in to leave a comment.