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.

Prismic's Live Preview feature uses cookies to build your previews on top of the browser to save you build time costs and allow you to see your draft content on your live website. Implementing something like this with a static site generator like Gatsby is normally quite hard, but thanks to the gatsby-source-prismic-graphql plugin this is mostly implemented for you. You'll just need to follow the steps below.

Some things to be aware of before you start:

  1. If your repo is set to private, then currently previews will not work.
  2. Gatsby-image/Image-sharp have been known to cause some issues with Previews because the image processing power of this plugin isn't available on the client-side. You should check out this article on why we recommend not using it.
  3. Some more complicated set-ups might require additional settings, if you need more help with that then reach out to us on our Community Forum!

Let's jump in and get started!

1. Gatsby Config File

To get the previews working, we need to update your plugin's configuration to include the path and preview options. Open your gatsby-config.js file and add the following settings.

Here is what the configuration should look like.

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'),
    }],
  },
}

You need to add the path config and specified the endpoint you want to use. Most people use '/preview' as the route that will handle their previews. Make note of whatever you choose, though, because this is important in a later step when you configure the Preview settings in your Prismic repository.

You also need to make sure to set previews to true. This simply turns on the preview functionality for your site.

By setting up the path config, you have created an endpoint in your project that will allow you to redirect to the correct page when previewing a document from Prismic. This is done by accessing a Link Resolver function that takes in a Prismic document object and returns the corresponding url for that page in your site. To learn more check out the Link Resolving article.

Here is an example of a Link Resolver function. Note that yours will likely be different than this depending your Custom Types and your website url structure.

Copy
const linkResolver = (doc) => {
  if (doc.type === 'page') return `/${doc.uid}`
  return '/'
}

export default linkResolver

As you can see here, if the link passed to the Link Resolver is of the type "page", then it will generate the url using the page's UID value. Anything else will return the root of the website: '/'. You will need to configure this file to handle any other routes that you wish to create for Prismic documents.

Now that you have your link resolver, you'll need to register it with the Gatsby/Prismic plugin. Open the gatsby-browser.js file and add the following:

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

3. Configure the Preview settings in Prismic

Next you need 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.

Creating a new Preview

The Link Resolver needs to match the value you entered in the path in your gatsby-config.js file. If you used anything other than '/preview' then make sure that it matches here.

Multiple previews

Note that you can have more than one preview configured. This example shows how to set up a preview for development with localhost, but you could also add a preview for your live site as well. Just enter the live website domain in the "Domain for your Application section".

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

4. Test the previews

Now that everything is in place, feel free to try out the previews. If you don't already have your website running, then launch the site.

Then in Prismic, do the following:

  1. Make a change to one of your documents in Prismic.
  2. 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.

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

Closing Previews

Exiting previews correctly To close the preview session and clear the cookies in your browser, click on the "X" button in the toolbar in the bottom left of the page.