Refactor Contentful Rich Text Field integration

[axe312ger]

Complex data models in combination with Contentful rich text can cause issues. The code can become slow, the worst case will crash the build process.

This is a follow up to #15084 and tries to fix #24221

More detailed description here: #24221 (comment)

• Instead of storing resolved Rich Text Document Data in GraphQL, we will store the raw unresolved document in GraphQL. This will already let our build process pass. But now we only have the raw Contentful Link available when rendering rich text.
• Next, we add a subfield to the rich text graphql field references for querying data of references entities via GraphQL.
• For rendering, we are going to introduce GraphQL biggest change. The current best practice is to use the official Rich Text Renderer directly with the GraphQL field result. We expose a new function from the source plugin, which will wrap documentToReactComponents and takes care of resolving the references based on our custom GraphQL Query data.

Code demo:

import React from "react"

import Layout from "../components/layout"
import SEO from "../components/seo"

/* Import the render function: */
import { renderRichText } from "gatsby-source-contentful/rich-text"

const IndexPage = ({ data }) => {
  return (
    <Layout>
      <SEO title="Home" />
      {data.allContentfulPage.nodes.map(({title, richTextField}) => (
        <div>
          <h1>{title}</h1>
          {/* Render the Rich Text field: */}
          {richTextField && renderRichText(richTextField, {
            // Same options as:
            // https://github.com/contentful/rich-text/tree/master/packages/rich-text-react-renderer
          })}
        </div>
      ))}
    </Layout>
  )
}

export const pageQuery = graphql`
  query {
    allContentfulPage(limit: 1) {
      nodes {
        title
        richTextField {
          raw
          # Query the fields you need on your references:
          references {
            contentful_id # contentful_id is required
            ... on ContentfulPage {
              title
            }
            ... on ContentfulProduct {
              name
            }
          }
        }
      }
    }
  }
`

export default IndexPage

[axe312ger]

I have a working reference subfield. But it only works for a single reference node type. https://github.com/gatsbyjs/gatsby/pull/24905/files#diff-dc42475a9f0ed45d6e1bf554ec9958a2R556

Next step is to allow all possible Contentful node types as reference.

[KyleAMathews]

Will this require a major release of gatsby-source-contentful?

[axe312ger]

@KyleAMathews this won't be breaking when not using rich text. Rich text users would require to extend their query if they use linked entities and change 2-3 lines of code per template file.

[DSchau]

@axe312ger

this won't be breaking when not using rich text. Rich text users would require to extend their query if they use linked entities and change 2-3 lines of code per template file.

this is breaking then, right? If a user has to change their code (e.g. if they're using RichText) then we should designate this release as such (e.g. bump to a new major version).

Nicely done here!

[axe312ger]

@DSchau yeah, even when its not likely that the page was rendering before the fix, we should mark it as breaking change

[axe312ger]

Thanks to @vladar we now have an interface for all Contentful content types.

Will now work on the rendering part!

[axe312ger]

Some features we will get with this PR:

• Properly request rich text referenced assets & entries via graphql
• This means you can finally render assets via fluid and fixed in a performant non-hacky way
• Neat side effect: You will be able to query multiple Contentful content types at once. For example: If you have a mixed list of news and products, you can now query them in one Query. Saving time and code for stitching the two arrays together into one list.

[axe312ger]

Note to myself:

Make sure to add migrations steps into the warnings!

[axe312ger]

I pushed the first version of the rendering function.

Usage is pretty simple:

1. import render function
2. Add fields you need from the references to your GraphQL query
3. Call the render function with the result of the query

import React from "react"

import Layout from "../components/layout"
import SEO from "../components/seo"

/* Import the render function: */
import { renderRichText } from "gatsby-source-contentful/rich-text"

const IndexPage = ({ data }) => {
  return (
    <Layout>
      <SEO title="Home" />
      {data.allContentfulPage.nodes.map(({title, richTextField}) => (
        <div>
          <h1>{title}</h1>
          {/* Render the Rich Text field: */}
          {richTextField && renderRichText(richTextField, {
            // Same options as:
            // https://github.com/contentful/rich-text/tree/master/packages/rich-text-react-renderer
          })}
        </div>
      ))}
    </Layout>
  )
}

export const pageQuery = graphql`
  query {
    allContentfulPage(limit: 1) {
      nodes {
        title
        richTextField {
          raw
          # Query the fields you need on your references:
          references {
            contentful_id
            ... on ContentfulPage {
              title
            }
            ... on ContentfulProduct {
              name
            }
          }
        }
      }
    }
  }
`

export default IndexPage

A few issues:

• Resolving the entries ist not as trivial, since we prefix the Contenful ids sometimes (!) with a c. We need to change the fixId function or just get rid of it? It is probably just a relict of old times: [1.0] [gatsby-source-contentful] Left-pad IDs starting with a number to make GraphQL happy #1276
• Still no support for assets as they have to be handled in a different way. Will probably split the references field up in {references { Entry: { ...}, Asset: { ... }}}
• There is a huge chunk of code for the resolveFieldLocales option. I do think we can remove all of it as the new code makes this feature obsolete. (Opinions welcome, I never used this feature!)
• The code is not locale aware yet. If your entry is available in multiple languages, you probably might get a random one of these for rendering a Rich Text Field.

Ideas and opinions very welcome. I will continue next week.

Have a great weekend,
Benedikt

[vladar]

Overall looks good to me 👍 but added a couple of minor suggestions inline.

[DanweDE]

I don't know much about Gatsby but usage of RT seems fine @axe312ger 👍

[DanweDE]

Looking at https://github.com/contentful/contentful-resolve-response it doesn't seem necessary to include the sys unless I am missing something.

[axe312ger]

It uses the type to create lookup keys and avoid id collisions

https://github.com/contentful/contentful-resolve-response/blob/master/index.js#L20