Optimizing Images in Gatsby with gatsby-plugin-image

Problem: Bloated image payloads on a Gatsby site

When you add many photographs to a blog or portfolio, the default img tag sends the same large file to every device, wasting bandwidth and hurting LCP.

Takeaway: Use gatsby-plugin-image to generate optimized, responsive assets at build time

Setup

Add the plugin to gatsby-config.js and optionally set defaults.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-image',
      options: {
        // quality: 80, // default 50 for JPEG, 75 for WebP
        // breakpoints: [320, 640, 960, 1280],
        // placeholder: 'blurred',
      },
    },
    // other plugins...
  ],
};

Run this in the project root; you need read/write access to the folder.

Usage

Import an image via GraphQL or a relative path and use StaticImage for fixed‑size graphics or GatsbyImage for fluid images.

import { GatsbyImage, getImage } from 'gatsby-plugin-image'
import { useStaticQuery, graphql } from 'gatsby'

const data = useStaticQuery(graphql`
  query {
    file(relativePath: { eq: "src/images/hero.jpg" }) {
      childImageSharp {
        gatsbyImageData(
          layout: FIXED
          width: 800
          height: 400
          placeholder: BLURRED
          formats: [AUTO, WEBP, AVIF]
        )
      }
    }
  }
`)

const image = getImage(data.file.childImageSharp)

export default function Hero() {
  return (
    

      
    
  )
}

Place the component where you need the image; the plugin will create multiple widths and WebP/AVIF versions during gatsby build.

Verification

1. Run gatsby build (or gatsby develop to see dev output) in the project root.
2. After the build finishes, look inside public/images (or the folder where images are emitted). You should see files like hero-800w.webp, hero-800w.avif, hero-400w.jpg, etc.
3. Open the generated HTML page in Chrome, open DevTools → Network, disable cache, reload, and check that the img tag has a srcset attribute listing multiple widths and that the loading attribute is set to lazy (if you enabled lazy loading).
4. Run Lighthouse (Audits → Performance) and note the reduction in total image bytes compared to a build without the plugin.

If you don’t see the expected files, confirm that the source image is present at build time and that the plugin is listed before any image‑transforming plugins.

Trade‑off

The biggest cost is build time: Sharp processes each source image into every requested size and format. A site with hundreds of high‑resolution photos can see build times increase from seconds to several minutes. Mitigate this by:

• Keeping source images reasonably sized (e.g., no larger than the maximum display width you need).
• Using the breakpoints option to limit the number of generated widths.
• Running image optimization on a CI cache or incremental build if your provider supports it.

Remote images

The plugin cannot fetch images from external URLs during build; they must be downloaded and committed to the repo first. Otherwise the build will fail with a “file not found” error.

Closing

By adding gatsby-plugin-image you get automatic srcSet, modern formats, and blur‑up placeholders without writing custom logic. Verify the output in the public folder and monitor build times to stay within your team’s limits.