Gatsby Image Optimization: Practical Implementation with gatsby-plugin-image

The Core Problem

When building performance-optimized Gatsby sites, image handling is often the biggest bottleneck. Unoptimized images can account for 60-80% of a page's total weight, destroying Core Web Vitals scores and user experience. The solution lies in gatsby-plugin-image, which provides automatic responsive sizing, lazy loading, and modern format conversion.

How gatsby-plugin-image Works

The plugin transforms static image imports into GraphQL queries that generate multiple image sizes at build time. When a component renders, it only downloads the appropriate size for the user's viewport and device pixel ratio. This happens through StaticImage for fixed dimensions and GatsbyImage for responsive layouts.

Basic Implementation Example

Start by installing the required packages:

npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp

Configure gatsby-config.js in your project root:

module.exports = {
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-transformer-sharp`,
      options: {
        blockType: 'div'
      }
    }
  ]
}

Create an optimized image component:

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

export default function HeaderImage() {
  return (
    <header>
      <StaticImage
        src="../../images/hero.jpg"
        alt="Website hero illustration"
        layout="fullWidth"
        formats=\[\'AUTO\', 'WEBP', 'AVIF'\]
        placeholder="blurred"
        loading="eager"
      />
    </header>
  )
}

For images sourced from GraphQL (like CMS content), use GatsbyImage with useStaticQuery:

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

export default function ContentImage() {
  const data = useStaticQuery(graphql`
    query {
      heroImage: file(absolutePathResp: { glob: "hero*.jpg" }) {
        childImageSharp {
          image {
            width: 1200
            height: 600
          }
          gatsbyImageData(
            width: 1200
            formats: [AUTO, WEBP, AVIF]
            placeholder: BLURRED
          )\n        }
      }
    }
  `)

  const image = getImage(data.heroImage)
  return <GatsbyImage image={image} alt="Dynamic hero" />
}

Key Configuration Options

Option	Values	When to Use
layout	fixed, constrained, fullWidth	fixed for icons, constrained for content images, fullWidth for banners
formats