How Images Work in Gatsby

Where possible, we always recommend storing your images in Agility CMS's Assets area. These are automatically deployed to a CDN and support basic image transcoding via query-strings. You can simply continue to use the CDN URLs provided for your content without any additional work.

However, one of the primary benefits of having a static website is that nothing on your site can change without a new build. This ensures your website updates are atomic. If you are using CDN links to images though, in your site, one could alter an image and that change would take effect immediately on your site. You'd also have no way of reliably rolling back your site to a previous version since the images on the CDN are managed separately.

Using Gatsby Plugin Image

With the release of Gatsby V3 and the new Gatsby Image plugin, we were able to create gatsby-image-agilitycms. This is a custom image component that takes images stored within Agility CMS and handles all of the hard parts of displaying responsive images that follow best practices for performance on your website or application.

Getting Started

The agilitycms-gatsby-starter already has this configured for you out of the box, however, if you want to include this on a new site, there are a few steps you need to take before you start using the gatsby-image-agilitycms component.

  1. Update the package.json in your Gatsby project to use the Gatsby V3 and install the new Gatsby Image Plugin:

    • npm install gatsby@latest
    • npm install gatsby-plugin-image
  2. Install gatsby-image-agilitycms and update the gatsby-source-agilitycms plugin to the latest version:

    • npm install @agility/gatsby-image-agilitycms
    • npm install @agility/gatsby-source-agilitycms@latest
  3. Add gatsby-plugin-image to your gatsby-config.js file.

    • module.exports = {
         plugins: [

Using the AgilityImage Component

To use the AgilityImage Component:

import { AgilityImage } from "@agility/gatsby-image-agilitycms"

The AgilityImage Component accepts the following props:

  1. image = The object of your image from Agility.
  2. layout = Determines the image sizes that are generated, as well as the resizing behavior of the image itself in the browser:
    • constrained
    • fixed
    • fullWidth


<AgilityImage image={image} layout={fullWidth} />

3 out of 3 found this helpful



Please sign in to leave a comment.