Skip to main content

Getting Started With ImageEngine and GatsbyJS

Jon Sæterås
  • Updated

Getting Started With ImageEngine and GatsbyJS

GatsbyJS is a node based static site builder which is very popular for JAM-stack sites and sites built with headless content management systems (CMS). The ImageEngine Gatsby plugin makes it very easy to speed up image delivery on your GatsbyJS site.

The plugin supports file based assets and also include built in support for popular headless CMSs like Contentful, Storyblok and Sanity as well as a convenient integration with the sharp based gatsby-plugin-image.

Installation

First, make sure you have your ImageEngine delivery address at hand. If you don't have an ImageEngine account, signup here.

Install the package inside your GatsbyJS project:

npm install @imageengine/gatsby-plugin-imageengine

If you intend to use ImageEngine together with gatsby-plugin-image, you also need to install gatsby-plugin-image and gatsby-plugin-sharptoo.

Configuration

Next, open the gatsby-config.js file. The gatsby-plugin-imageengine must be configured with at the ie_delivery_address and a source as the minimum:

plugins: [
  // ... other plugins
  {
    resolve: "@imageengine/gatsby-plugin-imageengine",
    options: {
       sources: [
            {source: "file"} 
       ],
        ie_delivery_address: "https://try.cdn.imgeng.in/"
  }
]

The example above specifies "file" as a source, and a specific delivery address for all sources. However, the plugin support multiple sources, each with different delivery addresses and as well as directives.

{
resolve: "@imageengine/gatsby-plugin-imageengine",
  options: {
    sources: [
      {
        source: "contentful",
        ie_delivery_address: "https://contentful123.cdn.imgeng.in/"
      },
      {
        source: "sanityio",
        ie_delivery_address: "https://sanity123.cdn.imgeng.in/",
        directives: {
            compression: "10"
        }
      },
      {
       source: "storyblok", 
       ie_delivery_address: "https://storyblok123.cdn.imgeng.in/", 
      },
      {source: "file"}
    ],
    ie_delivery_address: "https://default123.cdn.imgeng.in/",
    directives: {
        fit: "outside"
    }      
  }

In this case the built in Contentful source is specified with source: "contentful" and given an ImageEngine delivery address. All references to Contentful images will be using this delivery address.

Similarly, the Sanity.io source, specified by source: "sanityio", will get its dedicated delivery address and can be used together with other sources you may use on your site. The Sanity.io source also has additional directives assigned. This example sets the compression level to 10 for images.

source: "storyblok"will similarly automatically serve images from Storyblok through ImageEngine.

Any directives at the source level will override the global directives (and delivery addresses) defined at the top level.

Note: If you use gatsby-image or gatsby-plugin-image, it is recommended to set the fit directive to outside to make ImageEngine fit the image inside the markup container that Gatsby creates:

directives: {
    fit: "outside"
}

A complete list of directives can be found in the GraphiQL UI provided by GatsbyJS.

Write Custom sources.

If you need other sources than Sanity.io, Contentful and file, you can write your own to make the ImageEngineAsset nodes available.

In order to do that your source object has to specify both a "checker function" and a "transform function".

export type IECheckFunction = (node: any, options?: IEPluginOption, global_options?: IEPluginOptions) => boolean;
export type IETransformFunction = (node: any, options?: IEPluginOption, global_options?: IEPluginOptions) => void;

Then, this source must be specified in gatsby-config.js:

sources: [
    {
        source: "my-own-source",
        ie_delivery_address: "https://some-url.cdn.imgeng.in/",
        checker: my_own_source_checker,
        transform: my_own_transform
    }
]

Read more about custom sources and nodes here.

Usage

Once the plugin is configured, development can start. A complete example of a simple page may look like this:

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

export default function IndexPage({ data }) {
  return (    
    <GatsbyImage
      image={data.file.childImageEngineAsset.gatsbyImageData}
      alt="image"
    />
  )
}

export const query = graphql`
  query {
    file(name: {eq: "icon"}) {
      childImageEngineAsset {
        gatsbyImageData(height:200, width:100)
      }
    }
  }
`

This example will make use if the advanced options of gatsby-plugin-image and use ImageEngine at the image CDN.

Note: When developing locally and using the file source, the src attribute of the images will also be local because the ImageEngine CDN can't reach files that are not available on the internet.

If you want to use ImageEngine with a plain <img>, you can do that by changing the query slightly:

  query {
    file(name: {eq: "icon"}) {
      childImageEngineAsset {
        url(height:200, width:100)
        responsive_details(height:200, width:100)
      }
    }
  }

This query enable you to use a single url, or generate a responsive image tag with srcset:

    <img {...data.file.childImageEngineAsset.responsive_details}/>
    <img src={data.file.childImageEngineAsset.url}/>

The above will respectively output this markup:

<img src="https://xyz123.cdn.imgeng.in/static/53aa06cf17e4239d0dba6ffd09854e02/icon.png?imgeng=/w_100/h_200/m_cropbox">
<img width="100" height="200" sizes="(min-width: 100px) 100px, 100vw" srcset="https://xyz123.cdn.imgeng.in/static/53aa06cf17e4239d0dba6ffd09854e02/icon.png?imgeng=/w_25/h_50/m_cropbox 25w,
https://xyz123.cdn.imgeng.in/static/53aa06cf17e4239d0dba6ffd09854e02/icon.png?imgeng=/w_50/h_100/m_cropbox 50w,
https://xyz123.cdn.imgeng.in/static/53aa06cf17e4239d0dba6ffd09854e02/icon.png?imgeng=/w_100/h_200/m_cropbox 100w" src="https://xyz123.cdn.imgeng.in/static/53aa06cf17e4239d0dba6ffd09854e02/icon.png?imgeng=/w_100/h_200/m_cropbox">

The url resolver might be useful if you want to place the url directly in an <img> tag src attribute, pass it as a prop to some component, make a link, or for instance as a background-image on a CSS selector.

Image Formats

ImageEngine will automatically generate the best format for the browser and device without any additional work. However, it is still possible to be more explicit with image formats if desired.

In a gatsbyImageData query you can either specify format or formats.

gatsbyImageData(width: 500, height: 300, format: jpg)

In this case GatsbyImage will render an <img> tag with srcset and sizes and the ImageEngine urls will contain the format directive for jpeg.

Using formats on the other hand will, of more than one format is specified, generate a <picture> element with a fallback <img> element.

gatsbyImageData(height:200, width:100, formats:[NO_CHANGE,WEBP,AVIF])

This example will make at least 3 formats available for the users. Note that Gatsby is only generating the markup, bot the actual image varians. This will potentially save a lot of time building the site since no image processing is required.

In general, it is recommended to configure Gatsby so that Sharp doesn't generate different sizes and formats of images, and let ImageEngine help with that.

Complete example page

A very simple page displaying an image named `icon.png` inside the `src` folder tree.

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

export default function IndexPage({ data }) {
  return (    
    <GatsbyImage
      image={data.file.childImageEngineAsset.gatsbyImageData}
      alt="image"
    />
  )
}

export const query = graphql`
  query {
    file(name: {eq: "icon"}) {
      childImageEngineAsset {
        gatsbyImageData(height:200, width:100)
      }
    }
  }

Why gatsby-plugin-imageengine is a great alternative?

Gatsby do have some powerful image management features through the Gatsby image plugin based on Sharp. However, there are some key advantages using ImageEngine over the Gatsby image plugin:

  • Significantly reduced build time
  • GraphQL compatibility
  • GatsbyImage compatibility
  • Faster image delivery through the ImageEngine CDN
  • Use ImageEngine control panel to fine tune image delivery
  • More accurate image optimization with unlimited breakpoints and superior mobile support
  • Out of the box Client Hints support for pixel perfect sizing.

If you want to use ImageEngine in Gatsby without GraphQL, the @imageengine/react component can help you.

Also, the @imageengine/imageengine-helpers will help you generate ImageEngine compatible urls.

Related articles

Comments

0 comments

Please sign in to leave a comment.