Migrate to the recommended plugin

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. Lets quickly review the differences:

gatsby-source-prismic

  • Fetches data using Prismic's REST
  • Can be used along with Gatsby Cloud
  • The Link Resolver and the HTML Serializer are added inside the plugin configuration

gatsby-source-prismic-graphql

  • 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. Remove the old plugin and install the new one

First, delete the cache and node_modules directory; either manually or by running the following command:

Copy
rm -rf node_modules/ .cache

Then install the new plugin using the following command:

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

2. Update the gatsby-config.js

Open the gatsby-config.js file, replace the plugin config and configure it according to your project. Here is an example of what the config should look like:

⚠️ Replace the example config

Remember that you will need to update this with the repository name, access token, Link Resolver, etc., to match your project. This configuration is mere, for example, purposes.

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

module.exports = {
 plugins: [
 {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: 'example-repository-name',
        accessToken: 'example-access-token',
        releaseID: 'example-id',
        linkResolver: () => (doc) => linkResolver(doc),
        schemas: {
          page: require('./custom_types/example_type.json'),
        },
        lang: '*',
        prismicToolbar: true,
      },
    },
  ] 
}

3. Refactor your queries

✔️ Test the queries

Open the GraphQL playground tool at http://localhost:8000/__graphql after launching your project to test and discover the types and properties of your GraphQL schema.

Take a look at the differences in the Graphql query syntax; in both cases, we call all documents of the type Page, filtering them by their UID and language. We retrieve UID, notes, and one Slice with the name "Embed".

gatsby-source-prismic:

Copy
query MyPages($uid: String, $lang: String) {
  allPrismicPage(uid: {eq: $uid}, lang: {eq: $lang}) {
    edges {
      node {
        uid
        data {
          example_text {
            html
            text
          }
          body {
            ...on PrismicPageBodyExampleSlice {
              slice_type
            }
          }
        }
      }
    }
  }
}

gatsby-source-prismic-graphql:

Copy
query MyPages($uid: String, $lang: String) {
  prismic {
    allPages(uid: $uid, lang: $lang) {
      edges {
        node {
          _meta {
            uid
          }
          example_text
          body {
            ... on PRISMIC_PageBodyExampleSlice {
              type
            }
          }
        }
      }
    }
  }
}

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 remain the same in both plugins. Here are the fields that require no changes:

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

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

gatsby-source-prismic: To query a doc's metadata, add the items at the top level of the node key.

Copy
allPrismicPost {
 edges {
    node {
      id
      uid
      type
      lang
    }
  }
}

gatsby-source-prismic-graphql: Go one level down to the _meta key.

Copy
prismic {
  allPosts {
    edges {
      node {
        _meta {
          id
          uid
          type
          lang
        }
      }
    }
  }
}

Title and Rich Text

gatsby-source-prismic: Specify the values you need: text, html, and raw. (you'll usually only use raw).

Copy
example_title {
  text
  html
  raw {...}
}

gatsby-source-prismic-graphql: Add the API ID of the field.

Copy
example_title

Image

gatsby-source-prismic: Specify each value you're going to use; in this case, we're calling url, alt, dimensions, and the responsive thumbnail views of the image.

Copy
example_image {
  url
  alt
  dimensions {
    width
    height
  }
  thumbnail {...}
} 

gatsby-source-prismic-graphql: Add the API ID of the field.

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:

Copy
example_content_relationship {
  document {
    ... on PrismicExampleType {
      uid
      type
      lang
    }
  }
}

gatsby-source-prismic-graphql:

Copy
example_content_relationship {
  ...on PRISMIC_ExampleType {
    _meta{
      uid
      type
      lang
    }
  }
}

Link and Link to Media

gatsby-source-prismic: Specify the link_type and URL of our file of website.

Copy
example_link {
  link_type
  url
}

gatsby-source-prismic-graphql: Use a Union type in order to specify which fields we need for each link type.

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.

gatsby-source-prismic: Specify each of the available values that you want to retrieve.

Copy
example_embed {
  type
  url
 {...}
}

gatsby-source-prismic-graphql: Add the API ID of the field.

Copy
example_embed

Geopoint

gatsby-source-prismic: Specify the latitude and longitude values.

Copy
example_geopoint {
  latitude
  longitude
}

gatsby-source-prismic-graphql: Add the API ID of the field.

Copy
example_geopoint

Group

The field group's usage remains almost the same in both plugins; you still need to call the necessary fields that the group contains. In this example, the group has a Title field.

gatsby-source-prismic:

Copy
example_group {
  example_title {
   html
   text
  }
}

gatsby-source-prismic-graphql:

Copy
example_group {
  example_title
}

4. Access the retrieved data

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

gatsby-source-prismic:

Copy
const data = data.allPrismicPage.edges[0]

gatsby-source-prismic-graphql:

Copy
const data = data.prismic.allPages.edges[0]