Open
Description
Discussion for the upcoming major release: #38585
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-schema-generation
branch. - PRs for this release will be prefixed with
CTF-v6:
in the title - You can find a prerelease here: gatsby-source-contentful: Next Major Version Public Test #38585
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. (CTF-next: Generate GraphQL schema based on Contentful Content Types #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. (CTF-next: Generate GraphQL schema based on Contentful Content Types #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 (refactor: align Rich Text field structure to Contentful GraphQL API #31122)
references
is now calledlinks
and will always be available. This allows querying__typename
and data fromsys
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 (refactor: flatten Contentful asset data structure to match GraphQL API schema #31115)
- Rename internal types with a scheme that avoids name collisions with content type names (CTF-v6: Rename schema types #31286)
- JSON fields are now real GraphQL JSON fields. This avoids the
- References for now use the
ContentfulEntry
interface. This should change depending on the field validation. (Either single type, union or the interface) (CTF-next: use union for reference fields with validation #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 (CTF-next: codemods to help for migration #35113)
-
introduce new metadata/tags feature aka the newwill be released earlier via feat(contentful): add support for tags #31746metadata.tags
property - Already done in prior release: Remove gatsby-image support chore(gatsby-image): move to deprecated plugins #31654
Next action items
-
sys.type
is the entity type (Entry, Asset), so it should not becomesys.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) (CTF-next: Generate GraphQL schema based on Contentful Content Types #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. (CTF-next: Generate GraphQL schema based on Contentful Content Types #30855)
- Rich Text fields no more need to
JSON.stringify()
and rich text renderer no more needs toJSON.parse()
(CTF-next: Generate GraphQL schema based on Contentful Content Types #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 refactor: remove reference resolve by Contentful SDK and clean up #34561)
- Reconsider node-per-locale structure, this may lead to massive node count reduction (POC: CTF-next: locale per context (DRAFT) #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 fieldfieldNameMarkdown
, we still might need to make it configurable
Examples and test projects
- update e2e-test/contentful (CTF-next: Generate GraphQL schema based on Contentful Content Types #30855)
- update
examples/using-contentful
(CTF-next: migrate using-contentful #31270) -
updateDeprecated featurebenchmarks/contenful
-
figure out what to do inDeprecated featurepackages/gatsby-recipes/src
-
updateDeprecated featureexamples/recipe-sourcing-contentful