gatsby-source-contentful@4.0.0 Rich Text Changes/Migration

[LekoArts]

Description

With version 4.0.0 the Rich Text experience was changed. Please use this umbrella discussion to share migrations or ask questions or report possible bugs.

@axe312ger can share more information then.

Related issues

#28052
#28074

[mikaelkristiansson]

Not sure if this is a bug or just a miss in the documentation but when setting a reference to an Asset it will not include it unless you add the key __typename in the graphQL query.
so like this:

body {
      raw
      references {
        ... on ContentfulAsset {
          contentful_id
          __typename
          file {
            url
          }
        }
      }
    }

this is because if you use richTextRender function it will divide the types by that key.
https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-contentful/src/rich-text.js#L30

It might have to do something with this comment? #25249 (comment)
I havent tried out the useNameForId: false yet though.

[axe312ger]

I'd love to include id & type automatically, lets see if we find a solution :)

[axe312ger]

Looks like we can, I'll create an issue out of your comment :)

[gusliedke]

If you don't add contentful_id richText.js will return null for references;

[adstr123]

This was a big one for me. I had no idea I needed __typename in my query from reading the migration guides from v2 or documentation. Is this something that can be done automatically as @axe312ger has mentioned (I don't see an issue logged btw) or is this just something that needs attention brought to it in the documentation?

[axe312ger]

@adstr123 all documentation and migration should contain __typename for a while. Where did you look at?

[gregoralbrecht]

I'm trying to upgrade to v4 of gatsby-source-contentful but can't get it to work. I'm querying the rich text like this (unchanged except for the raw instead of json):

blocks {
  ... on ContentfulBlockRichText {
    body {
      raw
    }
  }
}

Which worked fine before the upgrade. If I pass raw down to the new renderRichText(raw, {}), I get an error:

SyntaxError: Unexpected token u in JSON at position 0
    at JSON.parse (<anonymous>)
    at renderRichText (rich-text.js:13)
    at RichText (index.jsx:101)
    at renderWithHooks (react-dom.development.js:14804)

Running JSON.parse(raw) seems to work perfectly fine, so I've run out of ideas...

[mikaelkristiansson]

when passing it to renderRichText make sure you pass in the parent and not raw, so:

renderRichText(body);

because it will extract raw from the object you are passing into renderRichText. As you can see here: https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-contentful/src/rich-text.js#L4

[gregoralbrecht]

Well... that was a quick fix, thank you! My bad, I never spotted that difference in the code example, since I thought renderRichText was identical to documentToReactComponents. Makes sense, though, since it needs references as well.

[axe312ger]

The readme does not really document that function expect here:

https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful#rendering

Should I add a section that explains that function and parameters?

[gregoralbrecht]

@axe312ger I think having more examples of this might be very helpful! Here are a few things I stumbled upon:

1. The example you linked to has a typo: richTextField is not defined, right?
2. It seems like we have to query __typename, too? See the other comment above. Even if this is resolved later, it should probably be in the docs.
3. pageContext seems irrelevant?
4. We query allContentfulBlogPost, yet receive data.contentfulBlogPost? Is that correct?

[axe312ger]

@axe312ger I think having more examples of this might be very helpful! Here are a few things I stumbled upon:

1. The example you linked to has a typo: richTextField is not defined, right?

I don't know. Thats just a field name. It's up to you how you name your fields in Contentful

2. It seems like we have to query __typename, too? See the other comment above. Even if this is resolved later, it should probably be in the docs.

I added it to the readme

3. pageContext seems irrelevant?

Remove it

4. We query allContentfulBlogPost, yet receive data.contentfulBlogPost? Is that correct?

The query and the code are just examples: I adjusted them to be aligned with each other.

PR for changed readme: #29029

[gregoralbrecht]

Does anyone have recommendations on how to handle content types that might (or might not) be included in Rich Text? Let's imagine a simple content type BlogPost of type Rich Text. It might contain other content types (e.g., BlogPostImage, BlogPostCodeSnippet, ...) that aren't necessarily included, but might be at some point. Since all content is coming from Contentful, this might change at any time.

[axe312ger]

your query is invalid, please adjust your query structure:

contentfulPortfolioItem(slug: { eq: $slug }) {
  id
  title
  description: projectDescription {
    raw
    references {
      ... on ContentfulAsset {
        contentful_id
        file {
          url
          contentType
        }
      }
    }
  }
}

[abdojulari]

It is really sucks. The documentation is a flop. Why is it a big to display an image from contentful?

[axe312ger]

@abdojulari Sorry for you disliking the documentation.

Any suggestions?

What do you mean by Why is it a big to display an image from contentful??

[EdPike365]

I just wrote a Medium post on how to fix the "optional embeds in rich text" issue. Here: https://edpike365.medium.com/gatsby-contentful-rich-text-migrate-to-gatsby-source-contentful-version-4-in-early-2021-321904587470

[aericson]

I just wrote a Medium post on how to fix the "optional embeds in rich text" issue. Here: https://edpike365.medium.com/gatsby-contentful-rich-text-migrate-to-gatsby-source-contentful-version-4-in-early-2021-321904587470

@EdPike365 Just wanted to say thanks for the article, was very helpful :)

[RichardH9L]

contentful_id is sometimes of type String and sometimes of type String! Is this a bug? If not, what can I do to prevent this from happening?

This is a problem when required to use contentful_id on creating references

body {
        raw
        references {
          __typename
          ... on ContentfulArticle {
            contentful_id
            slug
          }
          ... on ContentfulVideo {
            contentful_id
            slug
          }
          ...

Error:

Fields "contentful_id" conflict because they return conflicting types String and String!. Use different aliases on the fields to fetch both if this was intentional.

GraphQL request:56:13
55 |           ... on ContentfulArticle {
56 |             contentful_id
   |             ^
57 |             id

GraphQL request:125:13
124 |           ... on ContentfulVideo {
125 |             contentful_id
    |             ^
126 |             url

I worked around it by creating an alias for one of the fields.

I'm using gatsby 2.28.0 and gatsby-source-contentful@4.2.0, also tried 4.3.0-next.1

[axe312ger]

@pfarnach your query looks fine, what do you mean by aliasing the first contentful_id and then assigning it to contentful_id later in code.?

[pfarnach]

@pfarnach your query looks fine, what do you mean by aliasing the first contentful_id and then assigning it to contentful_id later in code.?

Since renderRichText needs the contentful_id property to properly resolve references in the raw text (but I can't query for both contentful_ids at the same time), the relevant part of my query ends up looking like:

article {
  raw
  references {
    ... on ContentfulAsset {
      __typename
      contentful_id_alias: contentful_id
      title
      fluid(maxWidth: 1200) {
        src
      }
    }
    ... on ContentfulMyCustomWidget {
      __typename
      contentful_id
      title
    }
  }
}

and the code that adds in the contentful_id property looks like:

retVal.references = references?.map(ref => {
  if (ref.contentful_id_alias) {
    ref.contentful_id = ref.contentful_id_alias;
  }
  return ref;
});

Pretty gross -- let me know if I'm missing something obvious or if there's a better workaround.

[axe312ger]

Querying both without should absolutely work. Looks like this is a bug

[axe312ger]

Want to create a ticket out of it?

[pfarnach]

I spent some time trying to reproduce this in a smaller project but was unable to. The issue may be related to different plugins not playing together nicely. @RichardH9L can you give us some insight into your particular setup (e.g. what plugins you were using and the general project setup)?

[abdojulari]

Thanks for reaching out to me. I am sorry with the hash comment though. I must start with commendations, you have put up a good documentation. Nevertheless, it is necessary to update the documents when things change. For instance, it used to be body { JSON } but not split into body { raw references { } }. There should be a documentation to that effect that is straightforward to approach for any developer regardless our levels. I am a beginner, life was miserable until I found a solution through someone on YouTube. Thank you for reaching out and I am very sorry. Thank you for your time. Abdul

…

On Mon., Feb. 8, 2021, 6:56 a.m. Benedikt Rötsch, ***@***.***> wrote: @abdojulari <https://github.com/abdojulari> Sorry for you disliking the documentation. Any suggestions? What do you mean by Why is it a big to display an image from contentful?? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#28098 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC7SSTVJIISY5B6NGGADKBDS57GPBANCNFSM4TW6GGQQ> .

[mareksuscak]

To be quite frank with you all, the new references field further extends an already existing and pretty serious flaw of this plugin which is described in its documentation and summarized in the following quote:

At the moment, fields that do not have at least one populated instance will not be created in the GraphQL schema.

Why? I'm glad you asked! Read on.

Before v4 came out, we had to fight this plugin by creating at least one entry for each content type that would populate all optional fields to ensure that the GQL schema generated by Gatsby at build time is stable and doesn't change depending on the content. However, the references inside rich text fields weren't affected by this issue because they were not individually queryable as it was all taken care of by the plugin itself.

After v4, this issue now affects rich text field references as well which means that we not only need to maintain redundant entries with all of the optional fields filled out, now we also need to make sure that all rich text fields that support different kinds of embedded entries, entry hyperlinks or asset hyperlinks need at least one entry that lists out at least one instance of each referenced type which is really insane if you ask me. Consider the following numbers:

1. We use 53 rich text fields across 43 different content types
2. Each rich text field allows one or more of the following reference types:
   a. entry hyperlinks
   b. asset hyperlinks
   c. embedded entries
3. We use different validation rules for the above reference types allowing certain types of entries to be embedded

As you can imagine, it'd be a TON of work to ensure GQL schema stability with such a large and dynamic content model.

Don't get me wrong, it would be a huge improvement over the previous solution if that wasn't the case, but given the aforementioned drawback, it's become unfeasible for us to migrate to newer versions due to all the extra work. Are there any plans to improve the situation and generate the schema from the validation rules as that's the only way to ensure stable schema? We can't be the only ones suffering from this issue or are we outliers? Is there anyone else who shares my point of view? Oddly enough, GraphQL API provided by Contentful itself is always generated correctly based on validation rules and not content. So what is preventing this plugin from doing the same or utilizing the existing GQL schema?

I'm not familiar enough with the implementation details and limitations and so I can't tell if there's a serious blocker preventing this from being implemented correctly but I'd be happy to take a stab at it if someone who's more familiar provides some context and pointers.

[tomlschmidt]

Do we have any update on this @axe312ger? It still is a substantial issue in my opinion.

[axe312ger]

@tomlschmidt see #31385

I agree with you but it is far from easy to fix. I expect to have public updates soon!

[healthierkamm]

I know its complicated, but the way you do it, is a working solution for now.

The GraphQL I'm using, which queries for linked entries, breaks when there isn't any content that actually links to an entity link. Is the recommended solution still to populate dummy content?

[axe312ger]

Yes, till #31385 is released 🙈

[healthierkamm]

hey, good to know; thanks for the reply

[awkale]

I've upgraded and switched my queries using raw but keep getting this

Also, was using import { documentToReactComponents } from '@contentful/rich-text-react-renderer' before the upgrade and now use import { renderRichText } from 'gatsby-source-contentful/rich-text'

here's my query and how I'm using it

contentfulMainDescription(page: { slug: { eq: "product-updates" } }) {
      name
      text {
        raw
      }
    }

{renderRichText(data.contentfulMainDescription.text)}

Has anyone seen this error?

[axe312ger]

@awkale what is the value of data.contentfulMainDescription.text?

You might want to check if it actually has a value before trying to render it