The new version of the Kontent source plugin for Gatsby was released earlier this year, and we already talked about it on Gatsbyʼs blog. In this article, I will show you the most significant changes, how to resolve them in your projects, and how long it will all take you.

Not a facelift

First of all, the new source plugin is brand new. The old implementation did not allow us to properly optimize performance and add new features related to Gatsby Cloud and preview functionalities. So the new implementation brings many benefits including:

• Performance. Itʼs currently the fastest source plugin among all headless CMSs.
• Support for incremental builds.
• Support for Gatsby Cloud that now also includes a free tier.

But letʼs take a look at what changed code-wise and what you will need to fix in your projects:

• Element property names now use snake_case instead of pascalCase
• Type resolvers were removed
• GraphQL nodes structure was slightly changed
• Relationships and contentItems property on types were removed

Youʼll find a complete migration reference guide on GitHub. Here, Iʼll go over some changes and explain what needs to be done in greater detail. I will also include a link to a YouTube stream where I am applying these changes to the Kentico Advantage project built with Gatsby source plugin v2.

Element property names now use snake_case instead of pascalCase

This change affects some property names like imageId and urlSlug that are used for rich text fields. But make sure to also check all your other properties to see if their name changed to snake_case. You can do so using the GraphiQL explorer at http://localhost:8000/___graphiql.

Type resolvers were removed

YouTube stream link

This includes both rich text and URL slug resolutions. The previous version of the plugin set the resolution for all types during the build regardless of the resolved data being ever used. The .resolvedHTML property was removed, and the best practice now is to use the new RichTextElement component.

First, you need to install the following npm package that contains the component:

npm install @kentico/gatsby-kontent-components

Then import the RichTextElement into your page, template, or component:

import { RichTextElement } from "@kentico/gatsby-kontent-components"

And finally, use it:

<RichTextElement
      value={richTextElement.value}
      images={richTextElement.images}
      links={richTextElement.links}
      linkedItems={richTextElement.modular_content}
      resolveImage={image => {
        return (
          <img
            src={image.url}
            alt={image.description ? image.description : image.name}
            width="200"
          />
        )
      }}
      resolveLink={(link, domNode) => {
        const parentItemType = contextData.type // It is possible to use external data for resolution
        return (
          <Link to={`/${link.type}/partner/${parentItemType}/${link.url_slug}`}>
            {domNode.children[0].data}
          </Link>
        )
      }}
      resolveLinkedItem={linkedItem => {
        return <pre>{JSON.stringify(linkedItem, undefined, 2)}</pre>
      }}
      resolveDomNode={(domNode, domToReact) => {
        if (domNode.name === "table") {
          // For options - check https://www.npmjs.com/package/html-react-parser#options
          return (
            <div className="table-responsive">
              {domToReact([domNode])}
            </div>
          );
        }
      }}
    />

Now, this looks complicated, so letʼs take a closer look. If you were using the .resolvedHTML property earlier, your GraphQL query would probably look like this:

{
   ...
   content  {
       resolvedHTML
   }
}

Because the actual resolution of images, links, and other components happens now within the RichTextElement component, we need to supply all necessary data. The GraphQL query will look like this:

{
   ...
   content  {
       value
       images  {
           image_id,
           name,
           url,
           description
       }
       links  {
           
       }
       modular_content  {
           
       }
   }
}

You see, all the data is provided from the Gatsby node. No additional work for you. Just keep in mind to always include *_id data in the GraphQL queries even if youʼre not using them yourself. They allow the rich text resolver to properly identify specific images, links, and linked items.

The resolver functions have their default implementations outlined above, but feel free to adjust them to fit your needs.

As the last step, remove TypeResolver definitions from the deliveryClientConfig object in the gatsby-config.js file.

I personally like clean code and separated responsibilities, and this is definitely a huge step towards that. Having the resolution on a component level just feels right.

GraphQL node structure was slightly changed

YouTube stream link

The GraphQL node structure was changed to be unified with the raw Delivery API. This makes it easier to find and apply solutions in Kontent documentation. 

Youʼll need to adjust all GraphQL queries that use linked items or rich texts:

Linked items behind a 'value' property

The linked items are now nested and accessible via the new value property.

Linked items now require a type

Youʼll also need to change all GraphQL queries that use specific data from linked items. Take a look at this example:

{
   ...
   elements {
       content_item {
           elements {
               subphases {
                   elements {
                       title {
                           value
                       }
                   }
               }
           }
       }
   }
}

The adjusted GraphQL query needs to specify the type of the linked element:

{
   ...
   elements {
       content_item {
           value {
               ... on kontent_item_phase {
                   elements {
                       title {
                           value
                       }
                   }
               }
           }
       }
   }
}

Even though itʼs possible to omit the type if you just need data from the system element, I strongly recommend specifying it anyway. This change makes your code more error-proof as it wonʼt match an unexpected type among the linked items.

Relationships and contentItems property on types were removed

Relationships and contentItems property on types were removed to improve performance as they require some calculations that occur on every build. If you need these relationships, you can extend the Gatsby schema definition as described in this example on GitHub or compose the query from subqueries. I recommend the first approach as itʼll be easier to understand for newcomers to the project. If youʼre not sure what Gatsby Schema is, take a look at this video.

How long is this going to take?

In this article, I outlined the major changes between v2 and v6 of the Gatsby source plugin for Kentico Kontent. Bringing the Kentico Advantage project to the new version took me about six to eight hours. You can see it all in real-time on YouTube :-). Mostly it was about fixing small naming changes and adjusting the GraphQL queries. The functionality stayed almost untouched.

If youʼre facing a similar upgrade, let me know if you need any assistance or just want to brag you got it done faster :-)

Click here to check out the migration guide on GitHub.