How to use ImageEngine and Contentful with GatsbyJS

Contentful 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. Contentful 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 Contentful on a site built by GatsbyJS.

Getting started

First some node modules must be installed into your project.

To access the data managed in Contentful, we'll need the `gatsby-source-contentful module:

npm install gatsby-source-contentful

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

npm install @imageengine/gatsby-plugin-imageengine

With these plugins installed, Gatsby will create Graphql Nodes for your Contentful elements. When an element is of the type ContentfulAsset 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 images.ctfassets.net.

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

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

The source is defined as "contentful", 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-contentful plugin:

resolve: `gatsby-source-contentful`,
options: {
    spaceId: `your_space_id`,
    accessToken: CONTENTFUL_ACCESS_TOKEN,
    host: `preview.contentful.com`,
},

GraphQL

The plugin automatically creates child childImageEngineAsset 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 { GatsbyImage } from "gatsby-plugin-image";
import { useStaticQuery, graphql } from "gatsby";

const Lightbox = () => {
    const data = useStaticQuery(graphql`

      query {
        allContentfulAsset {
          nodes {
            childImageEngineAsset {
              gatsbyImageData(width: 500, height: 300, compression: 10)
            }
          }
        }
      }`);
    
    return (
      <div class="light-box">
        {data.allContentfulAsset.childImageEngineAsset.map(({ gatsbyImageData }, index) => {
    return <GatsbyImage key={`image-${index}`} image={gatsbyImageData} />;
  })}
      </div>
    );
}

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

Worth noting is that if you have enabled downloadLocal (downloads all Contentful assets to your GatsbyJS app), ImageEngine will reduce build time significantly because gatsby-plugin-imageengine make sure real time optimization happens on the CDN rather than by Sharp during build time.

Advantages by Using ImageEngine over Contentful

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

• ImageEngine is a dedicated Image CDN with superior performance.
• ImageEngine has superior support for mobile users.
• ImageEngine can be used across many image locations. Contentful + local file + 3rd parties etc.
• Convenient and flexible integration with GatsbyImage and other ways to display images
• Reduced build time for apps with local images.