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 3 and below of the gatsby-source-prismic plugin, the preview functionality was enabled using the same plugin. Now previews are handled with their own gatsby-plugin-prismic-previews plugin

Handling breaking changes

Update gatsby-browser.js and gatsby-ssr.js files

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, a CSS file must be imported to style the preview system's interface. Users of your app will only see an interface during a preview session.

  • After
  • Before
Copy
// Example gatsby-browser.js AND gatsby-ssr.js files

import * as React from 'react'
import { PrismicPreviewProvider } from 'gatsby-plugin-prismic-previews'
import 'gatsby-plugin-prismic-previews/dist/styles.css'

export const wrapRootElement = ({ element }) => (
  <PrismicPreviewProvider>{element}</PrismicPreviewProvider>
)
Copy
// Example gatsby-browser.js AND gatsby-ssr.js files

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, a single provider will be shared among all repositories.

Update pages and templates

In your preview-enabled page components or templates, update the withPreview() import to the withPrismicPreview() import and provide additional arguments to the function as described below.

  • After
  • Before
Copy
// Truncated Page.js example file

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,
  },
])
Copy
// Truncated Page.js example file

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 the withPrismicPreviewResolver import and update the arguments provided to the function as described below. The preview resolver page is typically created at 〜/src/pages/preview.js.

  • After
  • Before
Copy
// Truncated preview.js example file

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,
  },
])
Copy
// Truncated preview.js example file

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 the withPrismicUnpublishedPreview import and update the arguments provided to the function as described below. The unpublished preview page is typically created as part of the "Not Found" 404 page at 〜/src/pages/404.js.

Note that the page template components are imported using their default exports (import PageTemplate rather than import { PageTemplate }). This ensures that the template is wrapped with withPrismicPreview() as is required.

  • After
  • Before
Copy
// Truncated 404.js example file

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,
    }),
  },
])
Copy
// Truncated 404.js example file

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 referente of the preview plugin if you'd like to see the in-depth documentation of the plugin, its High Order Components and more.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.