Migration Guide: gatsby-source-prismic V3 to V4

This migration guide is going to help you upgrade the gatsby-source-prismic plugin from version V3 to V4 on your Gatsby project.


ūüēô Before Reading

If your site is using V2, in Gatsby and the gatsby-source-prismic plugin, please migrate both to V3 first:

The V4 release of gatsby-source-prismic brings several new features and fixes that make working with Prismic within Gatsby easier and more flexible. The changes result from real-world use cases from user feedback shared on GitHub, and the Prismic community forum.

What has changed?

Prismic's Gatsby support has been split into two plugins: gatsby-source-prismic and gatsby-plugin-prismic-previews. New features and changes for each are described below.

gatsby-source-prismic

This plugin is used to pull CMS data into Gatsby using Prismic's REST API.

  • Multiple repository support
  • Validate plugin options
  • Automatic Custom Types schema fetching (via the beta¬†Custom Types API)
  • gatsby-plugin-image¬†support
  • GraphQuery¬†support (replacement for fetchLinks option)
  • Serve media files from Link fields locally via localFile field
  • Download image and media files only when queried for faster start-up times
  • Full support for Embed fields with oEmbed data
  • Full support for¬†Integration Fields
  • Private plugin options, including repository names, access tokens, and schemas

gatsby-plugin-prismic-previews

This plugin is used to provide live previews client-side directly from the Prismic editor. The following changes are made over the preview functionality previously provided by the gatsby-source-prismic plugin.

  • Live refreshing as document changes are saved
  • Preview changes across all data and pages, not just the previewed document's page
  • Preview a release with multiple documents
  • Sharable preview links
  • Easier to use hooks and higher-order-components to integrate with your site
  • Private access tokens (optional)

Update your dependencies

To update your project to V4, first, you'll need to update your dependencies.

Update Gatsby

The latest version of Gatsby V3 is highly recommended when using gatsby-source-prismic V4. Update your package.json.

Copy
// Truncated package.json example file

{
  "dependencies": {
    "gatsby": "^3.3.0"
  }
}

Update gatsby-source-prismic

Then, update your package.json to use the latest version of gatsby-source-prismic.

Copy
// Truncated package.json example file

{
  "dependencies": {
    "gatsby-source-prismic": "^4.0.0"
  }
}

Add gatsby-plugin-image

Gatsby's image processing plugin, gatsby-plugin-image, is a dependency of gatsby-source-prismic. Install and Configure the plugin in your gatsby-config.js file.

  • npm
  • Yarn
Copy
npm install gatsby-plugin-image
Copy
yarn add gatsby-plugin-image

Add gatsby-plugin-prismic-previews

Preview functionality has been moved to its own plugin called gatsby-plugin-prismic-previews. Install and Configure the plugin in your gatsby-config.js file.

  • npm
  • Yarn
Copy
npm install gatsby-plugin-prismic-previews
Copy
yarn add gatsby-plugin-prismic-previews

If your site has the previous preview implementation provided by gatsby-source-prismic, you'll need to migrate it as well at the end of this guide. See the Migrate Previews to the preview plugin section below for more details.

Handling breaking changes

Provide all Custom Type schemas

In V3, providing your Custom Type schemas was required, but the plugin made no validation to ensure all Custom Type schemas were provided to it. If your repository contained a Custom Type called "Page" and another called "Blog", but only provided the schema for "Page", the plugin would continue to function. However, fields within the "Blog" custom type would not work correctly, leading to confusing results.

In V4, providing all Custom Type schemas is required. The plugin will check your repository for all configured Custom Types and ensure a schema has been provided for each.

Note: If at any point a Custom Type was created and used at least once; if it has since been disabled and/or removed from your repository, even if all documents of that type have been deleted, you still need to provide its schema.

Deleted documents can be fetched using a previous revision of your repository data, thus requiring the schema to be available.

If you no longer have access to the schema, you may provide an empty object as its schema.

  • After
  • Before
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        schemas: {
          // Include all your custom typeschemas
          page: require('./custom_types/page.json'),

          // If a custom type was used at one point, 
          // but has since been removed,
          // you may pass an empty schema object.
          an_unused_type: {},
        },
        // All other plugin options...
      },
    },
  ]
}
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        schemas: {
          page: require('./custom_types/page.json'),
        },
        // All other plugin options...
      },
    },
  ]
}

Update the queries

In V3, GraphQL types for your document types and fields use the following pattern:

Prismic${customType}${...fieldSpecificIdentifier}

Where ${fieldSpecificIdentifier} is based on a document's field name. For example:

  • PrismicPage: A "Page" document
  • PrismicPageBodyImages: An "Images" Slice in a "Body" Slice Zone for a "Page" document
  • PrismicPageBodyImagesItemType: An item for an "Images" Slice for a "Page" document

In V4, GraphQL types follow the same pattern, but adds the word "Data" after custom type. This allows for better organization of types. If your project references GraphQL types with your queries, such as in fragments, add "Data" to the type names. For example:

  • PrismicPage: A "Page" document
  • PrismicPageDataBodyImages: An "Images" Slice in a "Body" Slice Zone in a "Page" document
  • PrismicPageDataBodyImagesItemType: An item for an "Images" Slice

Remove shouldDownloadFile

In V3, the shouldDownloadFile plugin option allowed for determining if a document's image should be downloaded locally. This makes the file's data available by querying for the localFile field.

In V4, the shouldDownloadFile plugin option has been removed. Instead of relying on that plugin option to determine if a file should be downloaded, querying for the localFile field represents "opting in" to download the file. Conversely, not querying for the localFile field means the file will not be downloaded locally.

  • After
  • Before
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
         // All other plugin options...
      },
    },
  ]
}
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        shouldDownloadFile: () => true,
        // All other plugin options...
      },
    },
  ]
}

Update the Link Resolver and HTML Serializer

In V3, Link Resolvers and HTML Serializers were provided extra data that is not normally available when working with Prismic. The extra data, comprised of the field’s root document, the field’s name, and the field’s value, could be used to customize the responses on a per-document-type or per-field basis. While this can be helpful, it is non-standard, is a common source of issues, and is not widely used.

In V4, the linkResolver and htmlSerializer plugin options accept a standard Prismic Link Resolver and HTML Serializer function, respectively. Remove the extra function wrapper from your Link Resolver and HTML Serializer to make them compatible with V4.

  • After
  • Before
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        linkResolver: (doc) => `/${doc.id}`,
        htmlSerializer: (type, element, content, children) => {
          // Your HTML Serializer
        },
        // All other plugin options...
      },
    },
  ]
}
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        linkResolver: ({ node, key, value }) => (doc) => `/${doc.id}`,
        htmlSerializer: ({ node, key, value }) => (
          type,
          element,
          content,
          children,
        ) => {
          // Your HTML Serializer
        },
        // All other plugin options...
      },
    },
  ]
}

Replace fetchLinks with graphQuery

In V3, the fetchLinks plugin option allowed for providing a list of document fields to make available in your app's Link Resolver. This is necessary if your Link Resolver requires data from a linked document, such as a parent or category document.

In V4, the graphQuery plugin option provides the same functionality with greater control. The value provided to the graphQuery plugin option looks similar to a GraphQL query in that you can define exactly which fields you need in a document, including nested content. You can learn more at Prismic's GraphQuery documentation.

The fetchLinks option will continue to work in V4, but graphQuery is recommended over fetchLinks as it provides more control over the fields fetched for a document.

  • After
  • Before
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        graphQuery: `
        {
          page {
            ...pageFields
            parent {
              ...parentFields
            }
          }
        }
      `,
        // All other plugin options...
      },
    },
  ],
}
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        fetchLinks: ['page.parent'],
        // All other plugin options...
      },
    },
  ],
}

Remove typePathsFilenamePrefix

In V3, the typePathsFilenamePrefix plugin option allowed customizing the filename of a preview-specific file saved in your site's public folder. This file is used during client-side previews to restructure document data to match Gatsby's GraphQL API.

In V4, all preview functionality is moved to the preview plugin: gatsby-plugin-prismic-previews, which will always use a hashed filename and is not customizable. As this file is only used internally to make previews work correctly, direct access is not supported, and as such, the filename does not need to be known.

  • After
  • Before
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        // All other plugin options...
      },
    },
  ]
}
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        typePathsFilenamePrefix: 'prismic-typepaths---my-prefix',
        // All other plugin options...
      },
    },
  ]
}

Remove prismicToolbar

In V3, the prismicToolbar plugin option allowed for opting into loading the Prismic Toolbar on all pages. The Prismic Toolbar was optional and disabled by default.

In V4, all preview functionality is moved to the preview plugin: gatsby-plugin-prismic-previews, which requires the Prismic Toolbar and can only be customized to load either the legacy version or the current version.

  • After
  • Before
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        // All other plugin options...
      },
    },
  ]
}
Copy
// Truncated gatsby-config.js example file

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        prismicToolbar: true,
        // All other plugin options...
      },
    },
  ]
}

Use GraphQL over getNodes helpers in gatsby-node.js

In V3, nodes of a certain type, such as PrismicPage, could be fetched using Gatsby's getNodes or getNodesByType Node API helpers in gatsby-node.js. These functions returned the nodes with most of their data transformed as it would appear in a GraphQL query.

In V4, using those API helpers will still return the relevant nodes, but little to no data transformations will be available. Instead, you will receive something that mostly matches what is returned by Prismic's REST API. Rich Text fields, for example, would not include HTML or text fields.

To get the same data you would receive in a GraphQL query while in gatsby-node.js, replace getNodes and getNodesByType with a GraphQL query.

  • After
  • Before
Copy
// Truncated gatsby-node.js example file

exports.createPages = async (gatsbyContext) => {
  const { getNodesByType, graphql } = gatsbyContext

  const queryResult = await graphql(`
    query {
      allPrismicPage {
        nodes {
          uid
          url
        }
      }
    }
  `)

  for (const pageNode of queryResult.data.allPrismicPage.nodes) {
    // Do something with the page node
  }
}
Copy
// Truncated gatsby-node.js example file

exports.createPages = (gatsbyContext) => {
  const { getNodesByType } = gatsbyContext
  const pageNodes = getNodesByType('PrismicPage')

  for (const pageNode of pageNodes) {
    // Do something with the page node
  }
}

Use Imgix's gatsby-image fragments

In V3, using the gatsby-image integration with Imgix URLs required the use of specific fragments.

In V4, these fragments are deprecated and replaced by Imgix's official gatsby-image fragments. See the following list for conversions. The previous fragments will continue to be included in V4, but will be removed in V5.

Deprecated gatsby-image

gatsby-image is deprecated and replaced by gatsby-plugin-image. You may choose to upgrade to gatsby-plugin-image by querying for an image field's gatsbyImageData field and passing the result to the GatsbyImage component.

Old

New

GatsbyPrismicImageFixed

GatsbyImgixFixed

GatsbyPrismicImageFixed_noBase64

GatsbyImgixFixed_noBase64

GatsbyPrismicImageFixed_withWebp

GatsbyImgixFixed

GatsbyPrismicImageFixed_withWebp_noBase64

GatsbyImgixFixed_noBase64

GatsbyPrismicImageFluid

GatsbyImgixFluid

GatsbyPrismicImageFluid_noBase64

GatsbyImgixFluid_noBase64

GatsbyPrismicImageFluid_withWebp

GatsbyImgixFluid

GatsbyPrismicImageFluid_withWebp_noBase64

GatsbyImgixFluid_noBase64

Migrate Previews to the preview plugin

In V3, optional client-side previews could be integrated using higher-order components like withPreview() or React Hooks like usePrismicPreview().

In V4, all preview functionality is moved to the gatsby-plugin-prismic-previews plugin, which greatly improves preview functionality and better API security while keeping the API relatively similar to V3. All imports and usage will need to be migrated to the new plugin. If you are using previews currently, read the preview migration guide:

Or, If this is the first time you configure previews, read the dedicated guide:


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.