gatsby-plugin-hygraph
v1.0.3
Published
Unofficial plugin source from Hygraph (once GraphCMS)
Downloads
90
Maintainers
Readme
This simplifies and adds some new features
- Everything is handled in source nodes rather than later
- Compatible with Gatsby v5
- Parallel asset downloading
- Incremental downloading
- Handles locales
- Produces clean Rich Text Fields
- Locally caches assets to prevent downloading multiple times
Installation
npm install gatsby-plugin-hygraph
or
yarn add gatsby-plugin-hygraph
Configuration
We recommend using environment variables with your Hygraph
token
andendpoint
values. You can learn more about using environment variables with Gatsby here.
Authorization
You can also provide an auth token using the token
configuration key. This is necessary if your Hygraph project is not publicly available, or you want to scope access to a specific content stage (i.e. draft content).
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN
}
}
]
};
Options
| Key | Type | Description |
|--|--|--|
| endpoint
| String (required) | The endpoint URL for the Hygraph project. This can be found in the project settings UI. |
| token
| String | If your Hygraph project is not publicly accessible, you will need to provide a Permanent Auth Token to correctly authorize with the API. You can learn more about creating and managing API tokens here. |
| stages
| String (Default: ['PUBLISHED']
) | An array of Content Stages from your Hygraph project. Learn more. You can read more about using Content Stages here. |
| locales
| String (Default: ['en']
) | An array of locale key strings from your Hygraph project. Learn more. You can read more about working with localisation in Hygraph here. This builds complete models for each locale using the fallback locale. |
| allowedTypes
| String (Default: ''
) | A list of the types you want to import from your Hygraph schema into the application. Learn more. |
| typePrefix
| String _(Default: Hygraph
)_ | The string by which every generated type name is prefixed with. For example, a type of Post
in Hygraph would become hygraphPost
by default. If using multiple instances of the source plugin, you must provide a value here to prevent type conflicts. |
| downloadAssets
| Boolean (Default: true
) | Download and cache all Hygraph assets in your Gatsby project. Learn more. |
| downloadLocalImages
| Boolean (Default: false
) | Download non image assets (eg videos, svgs etc) |
| concurrency
| Number (Default: 50
) | How many asset downloads to run in parallel. |
| interval
| Number (Default: 1000
) | Intervals at which resources are to be retrieved from the Hygraph endpoint. The minimum interval is 300. The default interval is 1000. |
| assetsDir
| String (Default: .assets
) | Set to the name of the local cache directory |
| fragmentsDir
| String (Default: .fragments
) | The local project path where generated query fragments are saved. This is relative to your current working directory. If using multiple instances of the source plugin, you must provide a value here to prevent type and/or fragment conflicts. How |
| buildMarkdownNodes
| Boolean (Default: false
) | Build markdown nodes for all RichText
fields in your Hygraph schema. Learn more. |
| markdownFields
| Object (Default: {}
) | Which models/fields are markdown causing a markdown node to be built. Learn more. |
| cleanupRichText
| Boolean (Default: true
) | Create a cleaned node in RichText
fields in your Hygraph schema. These don't have empty elements and have replaced whitespace with a single space. |
Features
- Querying from content stages
- Querying localised nodes
- Set selected types to create a scheme
- Downloading local image assets
- Using markdown nodes
- Using markdown nodes
- Usage with
gatsby-plugin-image
- Working with query fragments
Querying from content stages
This plugin provides support to build nodes for entries from multiple Content Stages.
The provided Content Stages must be accessible according to the configuration of your project's API access. If providing a token
, then that Permanent Auth Token must have permission to query data from all provided Content Stages.
The example below assumes that both the DRAFT
and PUBLISHED
stages are publicly accessible.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
stages: ['DRAFT', 'PUBLISHED']
}
}
]
};
To query for nodes from a specific Content Stage, use the filter
query argument.
{
allHygraphProduct(filter: { stage: { eq: DRAFT } }) {
nodes {
name
}
}
}
Querying localised nodes
If using Hygraph localisation, this plugin provides support to build nodes for all provided locales.
Update your plugin configuration to include the locales
key.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
locales: ['en', 'pl']
}
}
]
};
To query for nodes for a specific locale, use the filter
query argument.
{
enProducts: allHygraphProduct(filter: { locale: { eq: en } }) {
nodes {
name
}
}
plProducts: allHygraphProduct(filter: { locale: { eq: pl } }) {
nodes {
remoteId
name
}
}
}
This creates local content nodes for all the locales produced. This allows simple multiple locale sites to be produced from partially localised content in the CMS.
Set selected types to create a scheme
If only certain types are to be used in the project this plug-in supports the ability to narrow the types to be downloaded to only selected types.
Update your plugin configuration to include the allowedTypes
key.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
allowedTypes: [
'Asset',
'Category',
'Product',
'Post'
]
}
}
]
};
After building the application in both development and production mode, only the schemes you add to the allowedTypes
key will be available. It is not necessary to add system schemas such as ScheduledOperation
, ScheduledRelease
or User
to the allowedTypes
key, as they are added automatically.
Usage with gatsby-plugin-image
Requires
gatsby-plugin-image
as a project dependency.
This source plugin supports gatsby-plugin-image
for responsive, high performance Hygraph images direct from our CDN.
Use the gatsbyImageData
resolver on your Hygraph_Asset
nodes.
{
allHygraphAsset {
nodes {
gatsbyImageData(layout: FULL_WIDTH)
}
}
}
gatsbyImageData
resolver arguments
| Key | Type | Description |
|--|--|--|
| aspectRatio
| Float | Force a specific ratio between the image’s width and height. |
| backgroundColor
| String | Background color applied to the wrapper. |
| breakpoints
| [Int] | Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate. |
| height
| Int | Change the size of the image. |
| layout
| GatsbyImageLayout (CONSTRAINED
/FIXED
/FULL_WIDTH
) | Determines the size of the image and its resizing behavior. |
| outputPixelDensities
| [Float] | A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a 400
px wide constrained image would generate 100
, 200
, 400
and 800
px wide images by default. Ignored for full width layout images, which use breakpoints
instead. |
| quality
| Int | The default image quality generated. This is overridden by any format-specific options. |
| sizes
| String | The <img> sizes
attribute, passed to the img tag. This describes the display size of the image, and does not affect generated images. You are only likely to need to change this if your are using full width images that do not span the full width of the screen. |
| width
| Int | Change the size of the image. |
For more information on using gatsby-plugin-image
, please see the documentation.
Downloading local image assets
If you prefer, the source plugin also provides the option to download and cache Hygraph assets in your Gatsby project.
To enable this, add downloadAssets: true
to your plugin configuration. This downloads all assets.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
downloadAssets: true
}
}
]
};
This adds a localFile
field to the Hygraph_Asset
type which resolves to the file node generated at build by gatsby-source-filesystem
.
If you also want to add support for downloading images to local files, add the following settings.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
downloadAssets: true,
downloadLocalImages: true
}
}
]
};
{
allHygraphAsset {
nodes {
localFile {
childImageSharp {
gatsbyImageData(layout: FULL_WIDTH)
}
}
}
}
}
Using markdown nodes
This source plugin provides the option to build markdown nodes for all RichText
fields in your Hygraph schema, which in turn can be used with MDX.
To enable this, add buildMarkdownNodes: true
to your plugin configuration.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
buildMarkdownNodes: true
}
}
]
};
Enabling this option adds a markdownNode
nested field to all RichText
fields on the generated Gatsby schema.
Usage with gatsby-plugin-mdx
These newly built nodes can be used with gatsby-plugin-mdx
to render markdown from Hygraph.
Once installed, you will be able to query for MDX
fields using a query similar to the one below.
{
allHygraphPost {
nodes {
id
content {
markdownNode {
childMdx {
body
}
}
}
}
}
}
Check out the demo source for an example of a full MDX implementation.
Using markdown fields
This source plugin provides the option to build markdown nodes for all RichText
fields in your Hygraph schema, which in turn can be used with MDX.
To enable this, add something like markdownFields: {Author: ['description']}
to your plugin configuration.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
markdownFields: {
Author: [
'description'
]
}
}
}
]
};
Enabling this option adds a descriptionMarkdownNode
field to the description
fields on the Author
schema. Other fields and schemas are added the same way
Working with query fragments
The source plugin will generate and save GraphQL query fragments for every node type. By default, they will be saved in a Hygraph-fragments
directory at the root of your Gatsby project. This can be configured:
If using multiple instances of the source plugin, you must provide a value to prevent type and/or fragment conflicts.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-hygraph',
options: {
endpoint: process.env.HYGRAPH_ENDPOINT,
token: process.env.HYGRAPH_TOKEN,
fragmentsDir: '.fragments'
}
}
]
};
The generated fragments are then read from the project for subsequent builds. It is recommended that they are checked in to version control for your project.
Should you make any changes or additions to your Hygraph schema, you will need to update the query fragments accrdingly. Alternatively they will be regnerated on a subsequent build after removing the directory from your project.
Modifying query fragments
In some instances, you may need modify query fragments on a per type basis. This may involve:
- Removing unrequired fields
- Adding new fields with arguments as an aliased field
For example, adding a featuredCaseStudy
field:
fragment Industry on Industry {
featuredCaseStudy: caseStudies(where: { featured: true }, first: 1)
}
Field arguments cannot be read by Gatsby from the Hygraph schema. Instead we must alias any required usages as aliased fields. In this example, the featuredCaseStudy
field would then be available in our Gatsby queries:
{
allHygraphIndustry {
nodes {
featuredCaseStudy {
...
}
}
}
}
Authors
The plugin can be used by anyone free of charge. The exception is the company Stellantis N.V. and any body working with the company.