How to use ImageEngine and Sanity.io with GatsbyJS

Sanity.io is a popular and powerful "Headless" Content Management System (CMS). Being "headless" basically means that the CMS doesn't come with a website on top, just an API where you can pull the content into a website built and hosted elsewhere.

Headless CMSs tend to be a popular choice for "JAM stack" based sites where the website is generated using a frontend framework or static site builder.

One popular static site builder is GatsbyJS. GatsbyJS offers a convenient way to pull content from GraphQL based APIs. Sanity is one of many headless CMSs that supports GraphQL.

This article explains the basic steps to make use of ImageEngine to optimize and serve images managed in Sanity on a site built by GatsbyJS.

Getting started

First some plugins must be installed into your project.

For Sanity.io API access, we'll need the `gatsby-source-sanity plugin:

npm install gatsby-source-sanity

Next, we'll need the ImageEngine plugin for GatsbyJS for image optimization:

npm install @imageengine/gatsby-plugin-imageengine

With these plugins installed, Gatsby will create GraphQL Nodes for your Sanity.io elements. For example, when an element is of the type allSanityImageAsset the ImageEngine plugin create a child node of childImageEngineAsset under it, that you can access through GraphQL.

Setup

First, you'll need your ImageEngine delivery address. If you don't have one yet, get one here. Note that the origin for the engine you create should usually be cdn.sanity.io.

The ImageEngine GatsbyJS plugin has built in support for Sanity.io. The only thing needed is to configure the plugin in `gatsby-config.js´:

{
resolve: "@imageengine/gatsby-plugin-imageengine",
  options: {
    sources: [
      {
        source: "sanityio",
      }
    ],
    ie_delivery_address: "https://sanity123.cdn.imgeng.in/",
  }

The source is defined as "sanityio", and the ie_delivery_address holds the ImageEngine delivery address. (Note the trailing /)

More details about the configuration can be found here.

Also, in the same section as the above, configure the gatsby-source-sanity plugin:

resolve: `gatsby-source-sanity`,
options: {
    projectId: `abc123`,
    dataset: `production`,
    token: process.env.SANITY_TOKEN,
    graphqlTag: 'default',
},

Basic usage

The plugin automatically creates child ImageEngineAsset nodes. This means you can use GraphQL to access these nodes and those contain all you need to use GatsbyImage or get an ImageEngine url.

Example GatsbyJS page:

import * as React from "react"
import { GatsbyImage } from "gatsby-plugin-image"
import { graphql } from "gatsby"

export default function IndexPage({ data }) {
  return (    
    <GatsbyImage
      image={data.allSanityImageAsset.edges[0].node.childImageEngineAsset.gatsbyImageData}
      alt="image"
    />
  )
}

export const query = graphql`
  query {
    allSanityImageAsset(
      filter: {id: {eq: "image-0860f9264ca11beb06b7c318afdad1b93d410181-5986x3991-jpg"}}
    ) {
      edges {
        node {
          childImageEngineAsset {
            gatsbyImageData(height: 200,width:100)
          }
        }
      }
    }
  }
`

All ImageEngine related nodes and properties are of course visible in the GraphiQL query tool too.

Advantages by Using ImageEngine over Sanity.io Built-in Image Delivery

Sanity.io offers some basic image manipulation features through its API. However, there are some key advantages to using ImageEngine in place of the Sanity.io Images API:

• ImageEngine is a dedicated Image CDN with superior performance.
• ImageEngine has superior support for mobile users.
• Convenient and flexible integration with GatsbyImage and other ways to display images