If you want to start a Gatsby project with Prismic, you’ll need to use a plugin to connect it. If you’re starting from scratch it's great because you can add the gatsby-source-prismic-graphql plugin from the beginning; but if you’re already in the development process this article will take you through the necessary steps to change from one to the other.

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

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

 

The differences between the two plugins

Both plugins work with Prismic, but the set up and usage its notoriously different from each other. Lets quickly review the differences:

gatsby-source-prismic

  • Fetches data using Prismic's REST
  • Previews must be coded separately
  • The Link Resolver and the HTML Serializer are added inside the plugin configuration

gatsby-source-prismic-graphql

  • Fetches data using Prismic's GraphQL API.
  • Provides support for Prismic's Preview feature out of the box. 
  • Provides an easy-to-configure interface for page generation.
  • Multiple language support
  • 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. Read more about this here.

  

How to migrate

1. Remove the old plugin and install the new one

First you need to delete the gatsby-source-prismic  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-graphql

 

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, pages, etc. to match your Prismic repository:

{
  resolve: 'gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'gatsby-source-prismic-test-site', // (required)
    accessToken: '...', // (optional)
    prismicRef: '...', // (optional)
    path: '/preview', // (optional, default: /preview)
    previews: true, // (optional, default: false)
    pages: [{ // (optional)
      type: 'Article',  // TypeName from prismic
      match: '/article/:uid', // Pages will be generated under this pattern (optional)
      path: '/article', // Placeholder page for unpublished documents
      component: require.resolve('./src/templates/article.js'),
    }],
    sharpKeys: [
      /image|photo|picture/, // (default)
      'profilepic',
    ],
  }

 

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 the uid field and language. We retrieve the metadata, title, description, and one Slice with the name "Embed".

gatsby-source-prismic

gatsby-source-prismic-graphql

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 meta fields.

Many times you’ll notice that in the gatsby-source-prismic-graphql plugin you just need the name of the field with no need to specify each element inside of it. 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 each value that you're going to need, in this case we're calling text, html and raw

title {
  text
  html
  raw {...}
}

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

title

  

Image

gatsby-source-prismic: You need to specify each value that you're going to need, 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 .

gatsby-source-prismic:

contentrelationship {
  document {
    __typename
    ...on PrismicEvent {
       type
       data {
        title {...}
      }
    }
  }
}

 
gatsby-source-prismic-graphql:

contentrelationship {
  __typename
  ...on PRISMIC_Event {
    _meta{
      type
    }
    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.

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 (The target  value is not available in the schema for the moment).  

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

 Learn more about querying links with Graphql here.
 

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 and you will receive everything.

embed

 

Geopoint

gatsby-source-prismic: 

geopoint {
  latitude
  longitude
}

 
gatsby-source-prismic-graphql: No need to specify the latitude and longitude, you will receive them 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. The only difference is the way you call the fields in the group will match everything above. 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  plugin you access data like this:

const data = data.allPrismicPage.edges.slice(0, 1).pop();

When you update to the gastby-source-prismic-graphql  plugin, you should access it like this instead:

const data = data.prismic.allPages.edges.slice(0, 1).pop();


After following this steps your project will be ready.

If you have any more questions don't hesitate to reach out to the Prismic team through the chat feature on the prismic.io website. For more documentation on Prismic + Gatsby check out Using Prismic with Gatsby.

Did this answer your question?