gatsby-plugin-contentful-optional-fields v2.2.2
gatsby-plugin-contentful-optional-fields
This package resolves an issue with gatsby-source-contentful and optional fields. When an optional field is defined on a content type in Contentful, at least one instance of that content type MUST contain an entry in that optional field. Otherwise, gatsby-source-contentful will not send that optional field in the return data, and suddenly your GraphQL queries are all borked. Uh-oh!
This package lets you manually define optional fields on each content type. When defined this way, your GraphQL queries will recieve NULL for unpopulated optional fields, instead of no value at all.
Installation
npm i gatsby-contentful-optional-fields
Quickstart
Include gatsby-plugin-contentful-optional-fields
in your gatsby-config.js
, with a map of optional fields and their primitive types in the plugin options.
{
resolve: 'gatsby-plugin-contentful-optional-fields',
options: {
optionalFields: {
ParentNode: {
optionalFieldName: 'String'
}
}
}
}
Setting up your config file
First, include gatsby-plugin-contentful-optional-fields
in your gatsby-config.js
.
{
resolve: 'gatsby-plugin-contentful-optional-fields',
options: {
optionalFields: {}
}
}
Next, you must provide a config object which defines all of your optional fields. The format for this object is as follows:
{
ParentNode: {
optionalFieldName: 'Optional field type'
}
}
For instance, if your ContentfulPages have an "optionalHeader" field, which is a relational field that links to a ContentfulHeader node, your config would look like this:
{
ContentfulPage: {
optionalHeader: 'Node'
}
}
The optional field type in this case is a Node (an object with child properties). Typically, your fields will either be of type 'Node', 'String' or 'Int'.
Your final plugin object should look something like this:
{
resolve: 'gatsby-plugin-contentful-optional-fields',
options: {
optionalFields: {
ContentfulPage: {
optionalCustomHeader: 'Node'
}
}
}
}
Usage in GraphQL queries
Now that your config file is set up, you can begin using optional fields in your queries. For optional fields of type Node, you will have to change your queries to use the spread operator (... on ContentType
), since child properties will not be guaranteed to exist if the optional field is not set, and therefore NULL is sent.
For instance, an optional query for a ContentfulHeader might look something like this (note the spread operator):
query {
contentfulPage {
optionalCustomHeader {
... on ContentfulHeader {
id
logo
links
}
}
}
}
Advanced example
{
resolve: 'gatsby-plugin-contentful-optional-fields',
options: {
optionalFields: {
ContentfulPage: {
optionalCustomHeader: 'Node',
optionalCustomTitle: 'String',
},
ContentfulBlogPost {
optionalAuthor: 'Node',
optionalPublishDate: 'Int'
}
}
}
}
query {
contentfulPage {
optionalCustomHeader {
... on ContentfulHeader {
id
logo
links
}
}
optionalCustomTitle
}
contentfulBlogPost {
optionalAuthor {
... on ContentfulAuthor {
id
firstName
lastName
}
}
optionalPublishDate
}
}