gatsby-plugin-hygraph

Unofficial plugin source from Hygraph (once Hygraph)

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 and endpoint 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

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

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

_realNormanik 💻

I don't like my current job so I do programming as a hobby. If you want to support my passion and help me get away from my full-time job at an outsourcing hotline then I encourage you to buy me a coffee 😃.

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.