CTF-v6: ☂️ Umbrella issue for next major version of gatsby-source-contentful

This umbrella issue collects all information about the upcoming new version of the gatsby-source-contentful plugin.

The core goal of this version is to align the GraphQL schema of the plugin to Contentfuls GraphQL API. These breaking changes allow us to introduce further features and performance improvements as well.

The new schema will be generated based on your content types instead of the existing content. This gives huge benefits in reliability and other things, but requires several rewrites of code, especially on GraphQL query level.

Branching & prerelease

• This new version will be developed in the feat/contentful-next branch. (It will be created as soon #30855 is ready)
• PRs for this release will be prefixed with CTF-v6: in the title
• There is no prerelease yet. Stay tuned.

Breaking changes

• The first comment contains all steps to migrate your code to this new version. Let me know if something is missing.
• The second comment highlights the changes to the schema, based on our Contentful e2e test Space

Goals

• Schema types now will be generated based on the Content Model in Contentful. Your project will no more break when a field has no values at all. (#30855)
• Align generated schema as close as possible to the Contentful GraphQL API. Queries from both environments should now be able to be more or less copy&pasted. (#30855)
  • JSON fields are now real GraphQL JSON fields. This avoids the There are conflicting field types in your data. warning and allows the JSON data structure to be changed in Contentful without breaking the Gatsby GraphQL Query
  • RichText:
    • Is now a simple object type
    • Fields split up references in entries and assets (#31122)
    • references is now called links and will always be available. This allows querying __typename and data from sys for all links at once as well.
  • Location fields now use a simple object type
  • Keep data from Contentfuls Common resource attributes within the sys property
  • Assets should have meta data like width on top level (#31115)
  • Rename internal types with a scheme that avoids name collisions with content type names (#31286)
• References for now use the ContentfulEntry interface. This should change depending on the field validation. (Either single type, union or the interface) (#31395) images-contentful) to match new asset structure
• update typescript typings or migrate to typescript
• create codemods to help migrating to this new major version (#35113)
• ~introduce new metadata/tags feature aka the new metadata.tags property~ will be released earlier via #31746
• Already done in prior release: Remove gatsby-image support #31654

Next action items

• sys.type is the entity type (Entry, Asset), so it should not become sys.contentType
• Reverse references should be restructured to use linkedFrom like Contentful does
• Execute the https://gatsby.dev/node-convention-deprecation
• the schema when using the Contentful Preview API actually differs slightly. For example required fields can be empty.

Update docs

• add descriptions to all/most GraphQL fields. Link to Contentful API docs and/or list edge cases like use -1 for max
• Update plugin readme

Changes in related plugins

• update gatsby-transformer-sqip to match new asset structure (as it is part of e2e-test/contentful) (#30855)
• update [gatsby-remark-images-contentful](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-

Potential performance improvements

• These changes will reduce the node count which will lead to improvements in bigger projects. (#30855)
• Rich Text fields no more need to JSON.stringify() and rich text renderer no more needs to JSON.parse() (#30855)
• We might be able to remove Contentful SDK link resolution and fully rely on our own. This would lead to performance improvements and code simplification (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-contentful/src/gatsby-node.js#L446-L492) (Fixed in master already via #34561)
• Reconsider node-per-locale structure, this may lead to massive node count reduction (POC: #31521)
• All (Long) Text fields still create their own node. As this is a potential performance issue, we should limit the number of fields that get parsed by gatsby-transformer-remark and others. Currently we see these options: a. make it configurable via directives and/or plugin config or b. move markdown in extra field fieldNameMarkdown, we still might need to make it configurable

Examples and test projects

• update e2e-test/contentful (#30855)
• update examples/using-contentful (#31270)
• update benchmarks/contenful
• ~figure out what to do in packages/gatsby-recipes/src~ Deprecated feature
• ~update examples/recipe-sourcing-contentful~ [Deprecated feature]

[axe312ger]

A small update:

The code mods are taking shape, see progress in #35113

I also discovered a few issues and things that are still to do. See Next action items in the first post.

[axe312ger]

@juanbiberretta This is great!

We currently testing the new version with some projects we got access to. As soon we are happy with the results, we will make a test version available to everyone!