Before we start, make sure the repository you're using has the GraphQL feature enabled. You can tell if its activated if you are able to see the GraphQL browser. (Just change "your-repository-name" to the name of your repo)

https://your-repository-name.prismic.io/graphql

The differences between the two plugins

Both plugins work with Prismic, but the set up and usage is 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 live in separated files. Build a Link Resolver first as a file /src/utils/linkResolver.js , so it can be registered as part of the configuration. In the gatsby-browser.js.

How to migrate

1. Remove the old plugin and install the new one

First you need to delete the gatsby-source-prismic-graphql plugin from your project, as well as the cache, and node_modules directory by running the following command:

rm -rf node_modules/ .cache

Then install the new plugin using the following command:

npm install gatsby-source-prismic

or

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 (keep in mind that you will need to update this with the repository name, access token, link resolver, etc. to match your project:

{
resolve: 'gatsby-source-prismic',
options: {
repositoryName: 'your-repo-name',
accessToken: '',
releaseID: 'example-eiyaingiefahyi7z',
linkResolver: ({ node, key, value }) => (doc) => {
// Your link resolver
},
fetchLinks: [
// Your list of links
],
htmlSerializer: ({ node, key, value }) => (
type,
element,
content,
children,
) => {
// Your HTML serializer
},
schemas: {
// Your custom types mapped to schemas
},
lang: '*',
prismicToolbar: true,
shouldDownloadImage: ({ node, key, value }) => {
// Return true to download the image or false to skip.
},
imageImgixParams: {
auto: 'compress,format',
fit: 'max',
q: 50,
},
imagePlaceholderImgixParams: {
w: 100,
blur: 15,
q: 50,
},
typePathsFilenamePrefix:
'prismic-typepaths---your-repo-name',
},
},

Please read the full reference to this plugin here

3. Refactor your queries

You can test query nodes created from Prismic using GraphQL and learn to use the GraphQL tool at http://localhost:8000/__graphql after launching your project to discover the types and properties of your GraphQL model.

Take a look at the differences in the Graphql query syntax, in both cases we are calling all pages, filtering them by their UID and language. We retrieve the metadata, title, description, and one Slice with the name "Embed".

gatsby-source-prismic

query Myposts ($uid: String, $lang: String){
allPrismicPage(uid: {eq: $uid}, lang: {eq: $lang}){
edges{
node{
id
uid
type
lang
data{
title{
html
text
}
description{
html
text
}
body{
...on PrismicPageBodyEmbed{
slice_type
}
}
}
}
}
}
}

gatsby-source-prismic-graphql

query Myposts($uid: String, $lang: String) {
allPages(uid: $uid, lang: $lang) {
edges {
node {
_meta {
id
uid
type
lang
}
title
description
body {
... on PRISMIC_PageBodyEmbed {
type
}
}
}
}
}
}

Differences in the structure of the schema

Some response fields remain the same in both plugins. Here are the fields that require no changes: Date, Timestamp, Color, Key Text, Select, and Number.

Fields that have a different structure are: Title, Rich Text, Content Relationship, Link, Link to media, Embed, Geopoint, Group, Image, and general document metadata fields.

Many times you’ll notice that in the gatsby-source-prismic plugin you'll need to go one level deep after the name of the field, to better understand this process, take a look at the differences listed below so that you know what to change in your code.

Note that in this example the API ID of the fields are the same as the field itself. e.g Embed field = embed .

Metadata

gatsby-source-prismic: To query the metadata of a document here you only need to add the items at the top level of the node key.

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


gatsby-source-prismic-graphql: Here you need to go one level down to the _meta key.

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


Title and Rich Text

gatsby-source-prismic: You need to specify the values that you're going to use, in this case we're calling text, html and raw .

title {
text
html
raw {...}
}


gatsby-source-prismic-graphql: Here you just needed the name of the field.

title

Image

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

image {
url
alt
dimensions {
width
height
}
medium {...}
thumbnail {...}
}


gatsby-source-prismic-graphql: Here you just need the name of the field.

image

Content Relationship

In this example we are querying a Content Relationship field that links to a document of the type event, and we're retrieving it's uid, and a title.

gatsby-source-prismic:

contentrelationship {
document {
...on PrismicEvent {
uid
data {
title {...}
}
}
}
}


gatsby-source-prismic-graphql:

contentrelationship {
...on PRISMIC_Event {
_meta{
uid
}
title
}
}

Link and Link to Media

In this example we are calling a Link field and querying for all possible results that may fall into each possible link type: an External link, a Media item link or a Document link to an event type.

gatsby-source-prismic: Here we need to specify all the possible fields to retrieve no matter which type of link it is, we only use the union type for Documents.

link {
link_type
url
size
document {
... on PrismicEvent {
id
uid
type
data {
title {...}
}
}
}
}


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

link {
__typename
...on PRISMIC__ExternalLink {
url
}
...on PRISMIC__ImageLink {
url
size
}
...on PRISMIC_Event {
title
_meta {
uid
id
type
}
}
}

Embed

The embed field has a numerous variety of values that can vary depending of the type of embed we are adding.

gatsby-source-prismic: Here you need to specify which keys you want to retrieve.

embed {
type
embed_url
...
}


gatsby-source-prismic-graphql: Here you just need the name of the field.

embed

Geopoint

gatsby-source-prismic:

geopoint {
latitude
longitude
}


gatsby-source-prismic-graphql: Here you'll receive the latitude and longitude automatically.

geopoint 

Group

The usage of the field group 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:

group {
title {
html
text
}
}


gatsby-source-prismic-graphql:

group {
title
}

4. Access the retrieved data

With the gastby-source-prismic-graphql plugin you access data like this:

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

After updating the gastby-source-prismic plugin, you should do it like this instead:

const data = data.allPrismicPage.edges[0]

If you have any more questions don't hesitate to reach out to the Community Forum.

Did this answer your question?