Migrate to gatsby-source-prismic

How to migrate from the 'gatsby-source-prismic-graphql' plugin to the officially supported 'gatsby-source-prismic' plugin.


The differences between the two plugins

Both plugins work with Prismic, but the setup and usage are different. Let's quickly review the differences:

gatsby-source-prismic

gatsby-source-prismic-graphql

  • Dynamic pages are generated inside the plugin configuration
  • Fetches data using Prismic's GraphQL API
  • The Link Resolver and the HTML Serializer are added manually to the Rich Text field

How to migrate

1. Install the new one

First, uninstall the old plugin:

  • npm
  • Yarn
Copy
npm uninstall -S gatsby-source-prismic-graphql
Copy
yarn remove gatsby-source-prismic-graphql

Then, install the new plugin:

  • npm
  • Yarn
Copy
npm install gatsby-source-prismic
Copy
yarn add gatsby-source-prismic

2. Update the plugin configuration

Open the gatsby-config.js file and replace the plugin configuration with the new one. Refer to the dedicated article to learn all the details about configuring the plugin.

Here is an example of how the new config looks like (All the values in this configuration are for example purposes only. Update it with the real values that match your project):

Copy
const linkResolver = require('./example-route-to-linkResolver')

module.exports = {
 plugins: [
 {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: 'your-repo-name',
        linkResolver: (doc) => linkResolver(doc),
        schemas: {
          page: require('./custom_types/page.json'),
          blog_post: require('./custom_types/blog_post.json'),
        },
      },
    },
  ] 
}

3. Refactor your queries

✔️ Test the queries

When running your project in development, you can open the GraphQL playground tool at http://localhost:8000/__graphql to test and discover the new types and properties of your GraphQL schema.

Take a look at the differences in the Graphql query syntax. For these examples, we query for the documents of the type page, filtering them by their UID and language, and retrieve a few fields, like the uid, a Rich Text field with the API ID of content, and one Slice with the API Id of embed.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
query MyPages($uid: String, $lang: String) {
  allPrismicPage(uid: {eq: $uid}, lang: {eq: $lang}) {
    nodes {
      uid
      data {
        content {
          raw
        }
        body {
          ... on PrismicPageDataBodyEmbed {
            slice_type
          }
        }
      }
    }
  }
}
Copy
query MyPages($uid: String, $lang: String) {
  prismic {
    allPages(uid: $uid, lang: $lang) {
      edges {
        node {
          _meta {
            uid
          }
          content
          body {
            ... on PRISMIC_PageBodyEmbed {
              type
            }
          }
        }
      }
    }
  }
}

4. Create pages dynamically

Automatic page generation is managed in different ways between the two plugins.

New plugin: You can generate your dynamic pages the Gatsby way. Using the File System Route API, or if you want more control over the page creation, you can use the createPages API.

In this example, we use the File System Route API to generate pages for the page type in the 〜/src/pages/{PrismicPage.url}.js file. This filename uses the nodes from the page query to create dynamic routes using the URLs defined in your LinkResolver.

Copy
// Example {PrismicPage.url}.js file

import * as React from 'react'
import { graphql } from 'gatsby'

export const PageTemplate = ({ data }) => {
  if (!data) return null
  const documents = data.prismicPage

  return (
    <section>
      <h1>{doc.data.example_key_text}</h1>
    </section>
  )
}

export const query = graphql`
  query PageQuery($id: String) {
    prismicPage(uid: { eq: $id }) {
       data {
         example_key_text
      }
    }
  }
`

export default PageTemplate

Deprecated plugin: Here, you needed to create your pages by providing a mapping configuration under the pages option in the plugin configuration in gatsby-config.js, like in the next example.

Copy
{
  resolve: 'gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'your-repo-name', 
    pages: [{
      type: 'Page',
      match: '/page/:uid',
      previewPath: '/page',
      component: require.resolve('./src/templates/page.js'),
    }],
  }
}

Differences in the structure of the schema

In the gatsby-source-prismic plugin, you'll often need to go one level deep after the field's API ID.

Some fields are the same in both plugins. Here are the fields that require no changes:

  • Date
  • Timestamp
  • Color
  • Key Text
  • Select
  • Number

The fields that have a different structure are:

  • Title
  • Rich Text
  • Content Relationship
  • Link and Link to media
  • Embed
  • Geopoint
  • Group
  • Image
  • and general document metadata fields.

Take a look at the differences listed below so that you know what to change in your code.

Example API IDs

Note: In this example, the fields' API ID is the same as the field itself with the prefix example_ appended at the beginning. e.g., Embed field = example_embed .

Metadata

New plugin: The doc's metadata is found at the top level of the node key.

Deprecated plugin: Go one level down to the _meta key.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
query MyQuery {
  allPrismicPost {
    nodes {
      id
      uid
      type
      lang
    }
  }
}
Copy
query MyQuery {
  prismic {
    allPosts {
      edges {
        node {
          _meta {
            id
            uid
            type
            lang
          }
        }
      }
    }
  }
}

Rich Text and Titles

New plugin: Specify the fields you need text, html, and raw. (Usually, you'll only use raw).

Deprecated plugin: Add the API ID of the field.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_rich_text {
  text
  html
  raw
}
Copy
example_rich_text

Image

New plugin Specify each value you're going to use; in this case, we're calling url, alt, dimensions, and the responsive thumbnails of the image.

Deprecated plugin: Add the API ID of the field.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_image {
  url
  alt
  dimensions {
    width
    height
  }
  thumbnails {...}
} 
Copy
example_image

Content Relationship

In this example, we query a Content Relationship field that links to a doc of the type event, and we're retrieving its uid, type, and lang.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_content_relationship {
  document {
    ... on PrismicEvent {
      uid
      type
      lang
    }
  }
}
Copy
example_content_relationship {
  ...on PRISMIC_Event {
    _meta{
      uid
      type
      lang
    }
  }
}

Link and Link to Media

New plugin: Specify the link_type and url of the media file or website. You can also retrieve documents as you would do with a Content Relationship field.

Deprecated plugin: Use a Union type to specify the fields for each link type.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_link {
  link_type
  url
}
Copy
example_link {
  __typename
  ...on PRISMIC__ExternalLink {
    url
  }
  ...on PRISMIC__ImageLink {
    url
    size
  }
  ...on PRISMIC_Event {
    title
    _meta {
      uid
      id
      type
    }
  }
}

Embed

The embed field has numerous values that can vary depending on the type of embed we add.

New plugin: Specify each of the available values that you want to retrieve.

Deprecated plugin: Add the API ID of the field.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_embed {
  type
  url
 {...}
}
Copy
example_embed

Geopoint

New plugin: Specify the latitude and longitude values.

Deprecated plugin: Add the API ID of the field.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_geopoint {
  latitude
  longitude
}
Copy
example_geopoint

Group

The field group's usage is almost the same in both plugins; you need to call the fields that the group contains. In these examples, the group has a Title field.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
example_group {
  example_title {
   html
   text
  }
}
Copy
example_group {
  example_title
}

Access the retrieved data

Example of how you'd access the retrieved data for each plugin.

  • gatsby-source-prismic
  • gatsby-source-prismic-graphql
Copy
const data = data.allPrismicPage.nodes
Copy
const data = data.prismic.allPages.edges[0]

Previews

Previews in the new plugin are supported thanks to gatsby-plugin-prismic-previews. Refer to the dedicated guide to learn how to configure this plugin:


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.