Migrate to the Preview Plugin

This guide will guide you though migrating your project preview configuration from gatsby-source-prismic to the preview plugin.

What has changed?

Previously in versions three and below of the gatsby-source-prismic plugin, the preview functionality was enabled using the same plugin. Now previews are handled with the gatsby-plugin-prismic-previews plugin.

Install the plugin

npm
Yarn

npm

Copy

npm install gatsby-plugin-prismic-previews

Yarn

Copy

yarn add gatsby-plugin-prismic-previews

Handling breaking changes

gatsby-browser.js and gatsby-ssr.js

In your gatsby-browser.js and gatsby-ssr.js files, replace the PreviewStoreProvider import with the PrismicPreviewProvider import. The new provider does not accept any props.

In addition to updating the context provider, you need to import a CSS file to style the preview system's interface. Users of your app will only see an interface during a preview session.

After
Before

After

gatsby-browser.js AND gatsby-ssr.js

Copy

import * as React from 'react'
import { PrismicPreviewProvider } from 'gatsby-plugin-prismic-previews'

export const wrapRootElement = ({ element }) => (
  <PrismicPreviewProvider>{element}</PrismicPreviewProvider>
)

Before

gatsby-browser.js AND gatsby-ssr.js

Copy

import * as React from 'react'
import { PreviewStoreProvider } from 'gatsby-source-prismic'

export const wrapRootElement = ({ element }) => (
  <PreviewStoreProvider>{element}</PreviewStoreProvider>
)

If you have multiple repositories in your app, they will share a single provider.

Update pages and templates

Change the withPreview() import to withPrismicPreview() and edit the arguments provided to the function in your preview-enabled page components or templates.

After
Before

After

Page.js

Copy

import * as React from 'react'
import { graphql } from 'gatsby'
import { withPrismicPreview } from 'gatsby-plugin-prismic-previews'

// Update the path to your Link Resolver
import { linkResolver } from '../linkResolver'

const PageTemplate = ({ data }) => {
  const document = data.prismicPage.data

  return (
    <div>
      <h1>{document.title.text}</h1>
    </div>
  )
}

export const query = graphql`
  query PageTemplate($id: String) {
    prismicPage(id: { eq: $id }) {
      _previewable
      data {
        title {
          text
        }
      }
    }
  }
`

export default withPrismicPreview(PageTemplate, [
  {
    repositoryName: 'your-repository-name',
    linkResolver,
  },
])

Before

Page.js

Copy

import * as React from 'react'
import { graphql } from 'gatsby'
import { withPreview } from 'gatsby-source-prismic'

const PageTemplate = ({ data }) => {
  const document = data.prismicPage.data

  return (
    <div>
      <h1>{document.title.text}</h1>
    </div>
  )
}

export const query = graphql`
  query PageTemplate($id: String) {
    prismicPage(id: { eq: $id }) {
      data {
        title {
          text
        }
      }
    }
  }
`

export default withPreview(PageTemplate)

In most cases, you will only need to move your repository name to the function's second argument.

Update the preview page

In your dedicated preview resolver page, update the withPreviewResolver() import to withPrismicPreviewResolver() and edit the arguments provided to the function. We usually create the preview resolver page at 〜/src/pages/preview.js.

After
Before

After

preview.js

Copy

import * as React from 'react'
import { withPrismicPreviewResolver } from 'gatsby-plugin-prismic-previews'

// Update the path to your Link Resolver
import { linkResolver } from '../linkResolver'

const PreviewPage = ({ data }) => {
  // Your Page component
}

export default withPrismicPreviewResolver(PreviewPage, [
  {
    repositoryName: 'your-repository-name',
    linkResolver,
  },
])

Before

preview.js

Copy

import * as React from 'react'
import { withPreviewResolver } from 'gatsby-source-prismic'
import { linkResolver } from '../path-to-your-linkResolver'

const PreviewPage = ({ data }) => {
  // Your Page component
}

export default withPreviewResolver(PreviewPage, {
  repositoryName: 'your-repository-name',
  linkResolver,
})

In most cases, you will only need to move your repository name to the function's second argument.

Update 404 page

In your dedicated unpublished preview page, update the withUnpublishedPreview() import to withPrismicUnpublishedPreview() and edit the arguments provided to the function. The unpublished preview page is typically created as part of the "Not Found" 404 page at 〜/src/pages/404.js.

Note that you must import the page template components using their default exports (import PageTemplate rather than import { PageTemplate }) to ensure that the template is wrapped with withPrismicPreview() as is required.

After
Before

After

404.js

Copy

import * as React from 'react'
import {
  withPrismicUnpublishedPreview,
  componentResolverFromMap,
} from 'gatsby-plugin-prismic-previews'

// Update the path to your Link Resolver
import { linkResolver } from '../linkResolver'

import PageTemplate from '../templates/PageTemplate'
import BlogPostTemplate from '../templates/BlogPostTemplate'

const NotFoundPage = () => (
  <section>
    <h1>Page not found!</h1>
  </section>
)

export default withPrismicUnpublishedPreview(NotFoundPage, [
  {
    repositoryname: 'your-repository-name',
    linkResolver,
    componentResolver: componentResolverFromMap({
      page: PageTemplate,
      blog_post: BlogPostTemplate,
    }),
  },
])

Before

404.js

Copy

import * as React from 'react'
import { withUnpublishedPreview } from 'gatsby-source-prismic'
import { PageTemplate } from '../templates/PageTemplate'
import { BlogPostTemplate } from '../templates/BlogPostTemplate'

const NotFoundPage = () => (
  <section>
    <h1>Page not found!</h1>
  </section>
)

export default withUnpublishedPreview(NotFoundPage, {
  templateMap: {
    page: PageTemplate,
    blog_post: BlogPostTemplate,
  },
})

Technical reference

Refer to the technical reference of the preview plugin if you'd like to see the in-depth documentation of the plugin and its High Order Components.

gatsby-plugin-prismic-previews

Can't find what you're looking for?

Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.