feat(gatsby-source-contentful): provide gql type definitions using content model introspection and schema-customization

examples/using-contentful/gatsby-node.js

@@ -2,6 +2,43 @@ const _ = require(`lodash`)
 const path = require(`path`)
 const slash = require(`slash`)
 
+exports.sourceNodes = ({ actions, schema }) => {
+  actions.createTypes(`
+    # This is needed if there aren't any MarkdownRemark nodes.
+    type MarkdownRemark implements Node @infer {
+      html: String
+    }
+  `)
+
+  actions.createTypes(
+    [`contentfulProductProductDescriptionTextNode`].map(typeName =>
+      schema.buildObjectType({
+        name: typeName,
+        fields: {
+          childMarkdownRemark: {
+            type: `MarkdownRemark`,
+            resolve: async (source, args, context) => {
+              const { path } = context
+              const result = await context.nodeModel.getNodesByIds(
+                { ids: source.children, type: `MarkdownRemark` },
+                { path }
+              )
+              if (result && result.length > 0) {
+                return result[0]
+              } else {
+                return null
+              }
+            },
+          },
+        },
+        extensions: {
+          infer: false,
+        },
+      })
+    )
+  )
+}
+
 // Implement the Gatsby API “createPages”. This is
 // called after the Gatsby bootstrap is finished so you have
 // access to any information necessary to programmatically
@@ -51,7 +88,7 @@ exports.createPages = ({ graphql, actions }) => {
         })
       })
     })
-    .then(() => {
+    .then(() =>
       graphql(
         `
           {
@@ -90,5 +127,5 @@ exports.createPages = ({ graphql, actions }) => {
           })
         })
       })
-    })
+    )
 }

examples/using-contentful/package.json

@@ -25,12 +25,9 @@
   ],
   "license": "MIT",
   "main": "n/a",
-  "resolutions": {
-    "contentful": "6.1.0"
-  },
   "scripts": {
     "develop": "gatsby develop",
     "build": "gatsby build",
     "start": "gatsby serve"
   }
-}
+}

examples/using-contentful/src/templates/category.js

@@ -76,7 +76,7 @@ export const pageQuery = graphql`
           width
         }
       }
-      product {
+      categoriesProduct {
         id
         productName {
           productName

examples/using-contentful/src/templates/product.js

@@ -83,14 +83,18 @@ export const pageQuery = graphql`
         }
       }
       brand {
-        companyName {
-          companyName
+        ... on ContentfulBrand {
+          companyName {
+            companyName
+          }
         }
       }
       categories {
-        id
-        title {
-          title
+        ... on ContentfulCategory {
+          id
+          title {
+            title
+          }
         }
       }
     }

packages/gatsby-source-contentful/README.md

@@ -156,14 +156,6 @@ List of locales and their codes can be found in Contentful app -> Settings -> Lo
 
 Prevents the use of sync tokens when accessing the Contentful API.
 
-## Notes on Contentful Content Models
-
-There are currently some things to keep in mind when building your content models at Contentful.
-
-1.  At the moment, fields that do not have at least one populated instance will not be created in the GraphQL schema.
-
-2.  When using reference fields, be aware that this source plugin will automatically create the reverse reference. You do not need to create references on both content types.
-
 ## How to query for nodes
 
 Two standard node types are available from Contentful: `Asset` and `ContentType`.
@@ -307,6 +299,103 @@ To get **all** the `CaseStudy` nodes with ShortText fields `id`, `slug`, `title`
 
 When querying images you can use the `fixed`, `fluid` or `resize` nodes to get different sizes for the image (for example for using [gatsby-image](https://www.gatsbyjs.org/packages/gatsby-image/)). Their usage is documented at the [gatsby-plugin-sharp](https://www.gatsbyjs.org/packages/gatsby-plugin-sharp/) package. The only difference is that gatsby-source-contentful also allows setting only the `width` parameter for these node types, the height will then automatically be calculated according to the aspect ratio.
 
+## Notes on Contentful Content Models
+
+### References
+
+Contentful reference fields will create [Union type](https://graphql.org/learn/schema/#union-types) fields. [Inline fragments](https://graphql.org/learn/queries/#inline-fragments) should be used to access the data on these fields.
+
+See below for a references example where you query for categories on a product:
+
+```graphql
+{
+  contentfulProduct {
+    name
+    price
+    categories {
+      # We are using inline fragment on Category type
+      # to access category fields
+      ... on ContentfulCategory {
+        title
+      }
+    }
+  }
+}
+```
+
+The above example assumes that you have `Product` and `Category` Content Models in your Contentful space, and that `Product` has a `categories` field that references `Category` entries.
+
+### Reverse references
+
+When using reference fields, be aware that this source plugin will automatically create the reverse reference. You do not need to create references on both content types. The name of the reverse reference will contain field and type names.
+
+See below for a reverse references example where you query for all products in a given category:
+
+```graphql
+{
+  contentfulCategory {
+    title
+    categoriesProduct {
+      name
+      price
+    }
+  }
+}
+```
+
+The above example assumes that you have `Product` and `Category` Content Models in your Contentful space, and `Product` has a `categories` field that references `Category` entries.
+
+### Markdown transformers on Long Text fields
+
+Version 3 of `gatsby-source-contentful` creates GraphQL schema directly from the Contentful Content Model and no longer infers fields from data.
+
+This means that queries will keep working even if your Contentful space doesn't have any fields in it.
+
+There is however, an edge case for transformed data - particularly for Long Text fields that can be transformed with `gatsby-transformer-remark` or `gatsby-mdx`. The Contentful plugin is not aware of transformers so you might need to provide hints for Gatsby to create `childMarkdownRemark`/`childMdx` fields.
+
+Here's an example of attaching `childMarkdownRemark`:
+
+```js
+// in your gatsby-node.js
+exports.sourceNodes = ({ actions, schema }) => {
+  actions.createTypes(`
+    # This is needed if there aren't any MarkdownRemark nodes.
+    type MarkdownRemark implements Node {
+      html: String
+    }
+  `)
+
+  actions.createTypes(
+    // list all types that need to have `childMarkdownRemark` attached
+    [`contentfulProductProductDescriptionTextNode`].map(typeName =>
+      schema.buildObjectType({
+        name: typeName,
+        fields: {
+          childMarkdownRemark: {
+            type: `MarkdownRemark`,
+            resolve: async (source, args, context) => {
+              const { path } = context
+              const result = await context.nodeModel.getNodesByIds(
+                { ids: source.children, type: `MarkdownRemark` },
+                { path }
+              )
+              if (result && result.length > 0) {
+                return result[0]
+              } else {
+                return null
+              }
+            },
+          },
+        },
+        extensions: {
+          infer: false,
+        },
+      })
+    )
+  )
+}
+```
+
 ## More on Queries with Contentful and Gatsby
 
 It is strongly recommended that you take a look at how data flows in a real Contentful and Gatsby application to fully understand how the queries, Node.js functions and React components all come together. Check out the example site at
@@ -353,5 +442,51 @@ documentToReactComponents(node.bodyRichText.json, options)
 
 Check out the examples at [@contentful/rich-text-react-renderer](https://github.com/contentful/rich-text/tree/master/packages/rich-text-react-renderer).
 
+## Migration to `gatsby-source-contentful` version 3:
+
+- Reference fields are always unions:
+  ```diff
+  {
+    contentfulProduct {
+      name
+      price
+      categories {
+  -     title
+  +     # We are using inline fragment on Category type
+  +     # to access category fields
+  +     ... on ContentfulCategory {
+  +       title
+  +     }
+      }
+    }
+  }
+  ```
+- Reverse reference fields now include referencing field name:
+  ```diff
+  {
+    contentfulCategory {
+      title
+  -   product {
+  +   categoriesProduct {
+        name
+        price
+      }
+    }
+  }
+  ```
+- Rich text fields now don't infer fields. Only available field is `json`. See [Contentful Rich Text](#contentful-rich-text) section on how to use it.
+- JSON object fields now don't infer fields:
+  ```diff
+  {
+    contentfulSomeType {
+      title
+  -   jsonField {
+  -     someFieldInsideJsonObject
+  -   }
+  +   jsonField
+    }
+  }
+  ```
+
 [dotenv]: https://github.com/motdotla/dotenv
 [envvars]: https://gatsby.dev/env-vars

packages/gatsby-source-contentful/package.json

@@ -13,7 +13,7 @@
     "base64-img": "^1.0.3",
     "bluebird": "^3.5.0",
     "chalk": "^2.3.2",
-    "contentful": "^6.1.0",
+    "contentful": "^7.6.0",
     "deep-map": "^1.5.0",
     "fs-extra": "^4.0.2",
     "gatsby-plugin-sharp": "^2.2.7",
@@ -37,7 +37,7 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "gatsby": "^2.0.33"
+    "gatsby": "^2.5.0"
   },
   "repository": {
     "type": "git",