Getting Started with Storyblok and ImageEngine with GatsbyJS

Storyblok is a powerful headless CMS. The ImageEngine GatsbyJS plugin has built in support for Storyblok and it's just a matter of configuration to get your Storyblok's assets optimized and delivered by ImageEngine.

In the following we'll learn how to use the ImageEngine GatsbyJS plugin together with Storyblok's plugin for GatsbyJS by querying content using GraphQL and use the Gatsby image component to manage images served by ImageEngine.

Getting Started

First we'll need to install some plugins

For Storyblok API access, we'll need the gatsby-source-storyblok plugin:

npm install gatsby-source-storyblok

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

npm install @imageengine/gatsby-plugin-imageengine

Gatsby will now create GraphQL Nodes for your Storyblok elements. For example, when an element is of the type allStoryblokEntry the ImageEngine plugin create a child node of childImageEngineAsset under it, that you can access through GraphQL.

Setup

At this stage, 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 a.storyblok.com.

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

plugins: [
{
  resolve: "@imageengine/gatsby-plugin-imageengine",
  options: {
    sources: [
      {
        source: "storyblok",
        ie_delivery_address: "https://example.cdn.imgeng.in",
        directives: {
          fit: "outside"
        }
      }
    ]
  }
},
{
  resolve: 'gatsby-source-storyblok',
  options: {
    accessToken: 'YOUR_ACCESS_TOKEN',
    version: 'draft', 
    spaceId: '#YOUR_SPACE_ID',
  }
},

"gatsby-plugin-image", "gatsby-plugin-sharp", "gatsby-transformer-sharp"]

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

Also note the directives. It is recommended to use the outside fit method for best compatibility with Gatsby images.

More details about the configuration can be found here.

Also make sure to configure the gatsby-source-storyblok so that Gatsby can query the correct space and versions. Read more about Storyblok access tokens.

Basic Usage

The ImageEngine plugin will now 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 obtain an ImageEngine url.

Example GatsbyJS page:

import * as React from "react"
import { graphql, HeadFC, PageProps, useStaticQuery } from "gatsby"
import { GatsbyImage, IGatsbyImageData } from "gatsby-plugin-image"


export default function IndexPage({ data }) {
    console.log("data: ", data)
    return (
      <div>
      <p>Image from Storyblok<br/>
      <GatsbyImage
        image={data.storyblok.edges[0].node.childImageEngineAsset.gatsbyImageData}
        alt="sanity"
      />
      </p>
      </div>
    )
  }
  
  export const query = graphql`
  query {
    storyblok: allStoryblokEntry(filter: {id: {eq: "storyblokentry-226977521-default"}}) {
      edges {
        node {
          childImageEngineAsset {
            gatsbyImageData(height: 600, width: 500)
          }
        }
      }
    }
  }
`

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

Also note that in the query above, the filter must be adapted to your needs in order to query for the desired content.

Advantages by Using ImageEngine

• 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
• 100% control over image manipulation through directives.