Setting up Previews

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

Welcome to the 6th article in the Gatsby/Prismic Getting started tutorial series. We'll be walking through the steps required to setup Live Previews for your Prismic pages.

Before reading

If you haven't already gone through the first five articles in this series, we recommend you start with the first article and work your way to this one. After that, this article will make much more sense.

Live Previews

Prismic's Live Preview feature allows you to preview your content changes and make sure everything looks as you want it to before you pull the trigger and publish the changes.

Gatsby is a static site generator, which typically make live previews much harder to do. But fortunately for us, previews are super easy to setup using the gatsby-source-prismic-graphql plugin that we're already using. This is one of the main reasons we recommend using this plugin over others out there.

Let's jump in and get started!

Configure the previews in your project

Open your project files if you don't already have them open. To get the previews working, we need to update our plugin's configuration to include the path and preview options. Open the gatsby-config.js file and update the plugin config.

Here is what the new configuration will look like. The first tab is the updated config for our plugin, the second tab shows you the updated config in the full gatsby-config.js file.

Update the repository name

Make sure that you keep the repositoryName the same as it is. If you accidentally copy & paste 'your-repo-name', you will need to update the value with your Prismic repository ID. In order to find this, go to your Prismic repository. For example, if the url for your repository is https://my-awesome-repository.prismic.io/ then you'll need to replace 'your-repo-name' below with 'my-awesome-repository'.

  • Updated config
  • Full gatsby-config.js file
Copy
{
  resolve: '@prismicio/gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'your-repo-name',
    path: '/preview',
    previews: true,
    pages: [{
      type: 'Page',
      match: '/:uid',
      path: '/page-preview',
      component: require.resolve('./src/templates/Page.js'),
    }],
  },
}
Copy
module.exports = {
  siteMetadata: {
    title: 'Gatsby + Prismic Tutorial',
    description: 'Learn how to integrate Prismic into your Gatsby project.',
  },
  plugins: [
    'gatsby-plugin-react-helmet',
    {
      resolve: 'gatsby-plugin-prefetch-google-fonts',
      options: {
        fonts: [
          {
            family: 'Lato',
            variants: ['400', '400i', '700', '700i', '900'],
          },
          {
            family: 'Amiri',
            variants: ['400', '400i', '700', '700i'],
          },
        ],
      },
    },
    'gatsby-transformer-sharp',
    'gatsby-plugin-sharp',
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        icon: 'src/images/favicon.png',
      },
    },
    {
      resolve: '@prismicio/gatsby-source-prismic-graphql',
      options: {
        repositoryName: 'your-repo-name',
        path: '/preview',
        previews: true,
        pages: [{
          type: 'Page',
          match: '/:uid',
          path: '/page-preview',
          component: require.resolve('./src/templates/Page.js'),
        }],
      },
    },
  ],
}

What we've done here is add the path config and specified that we want to use '/preview' as the route that will handle our previews. This is important in a later step when we configure the Preview settings in your Prismic repository.

The other change we made was to set previews to true. This simply turns on the preview functionality for your site.

The Preview Route

By setting up the path config, we have created an endpoint in our project to handle the previews. This is important because it will allow us to redirect to the correct page when previewing a document from Prismic.

You probably didn't realize it at the time, but you have already configured the redirects when you setup your Link Resolver in the second article in this series. You should already have this in place in your gatsby-browser.js file:

Copy
import './src/styles/reset.css'
import './src/styles/common.css'
import './src/styles/style.css'

import { registerLinkResolver } from '@prismicio/gatsby-source-prismic-graphql'
import linkResolver from './src/utils/linkResolver'

registerLinkResolver(linkResolver)

By registering your Link Resolver, you've made it so that the preview redirects will work.

Configure the Preview settings in Prismic

The next step we need to do is to update the Preview settings in your Prismic repository. Head to your Prismic repo and click on the settings button (the gear icon) in the bottom left to go to your settings. Head to Settings / Previews and create a new Preview. Use the following settings.

Adding the Preview in Prismic

The previews should be completely setup when you click on "Create my Preview."

Test the previews

Now that everything is in place, let's try out the previews. If you don't already have your website running, then open a terminal at the root of your project and run the npm start command to build and launch the site.

Then in Prismic, do the following:

  1. Navigate to your Content page and click to open one of your documents.
  2. Make a change to the document, then click "Save."
  3. Once it's finished saving, click on the Preview button (the eye icon in the top right).

This should open a new tab with your website and redirect to the correct page where you should now see your new content. To close the preview session, click on the "X" button in the toolbar in the bottom left of the page.

Well done, you can now preview your content changes live!

Next Steps

Congratulations, you've made it to the end of this step-by-step tutorial series! Next, we encourage you to explore further and learn more about how to use Gatsby & Prismic together. Some good resources are our example blog project and our developer documentation to learn more.