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]