Architecture note: Using gatsby-plugin-image for optimized image handling in Gatsby

Requirements

The goal is to deliver images that are responsive, lazily loaded, and automatically converted to modern formats (WebP/AVIF) with a srcset that matches the viewer’s viewport. This reduces payload and improves Largest Contentful Paint (LCP) without manual image processing.

Smallest suitable design

Add gatsby-plugin-image to the project, store source images in src/images, and reference them with either the StaticImage component (for images known at build time) or the GatsbyImage component (for images queried via GraphQL). Provide layout constraints such as fixed, fullWidth, or constrained so the plugin can generate the appropriate variants.

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-plugin-image',
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'images',
        path: `${__dirname}/src/images`,
      },
    },
    'gatsby-transformer-sharp',
    'gatsby-plugin-sharp',
  ],
};

// Example component using StaticImage
import { StaticImage } from 'gatsby-plugin-image';

function Hero() {
  return (
    
  );
}
export default Hero;

Trust and data boundaries

The plugin processes images exclusively during the gatsby build step. It reads files from the project’s filesystem, creates resized variants, and writes them to public/static. At runtime the browser only requests these static files; no file‑system access or arbitrary code execution occurs in the client, keeping the browser sandbox isolated.

Operational checks

1. After running gatsby build, inspect public/static for directories matching each source image name (e.g., hero.jpg) containing files like hero-800w.webp, hero-1200w.avif, etc. Their presence confirms successful variant generation.

2. Open the site in Chrome DevTools, enable network throttling (e.g., Slow 3G), and reload a page containing the image. Verify that only one request is made for an image whose width matches the viewport (or the nearest larger width in the srcset).

3. Run Lighthouse (lighthouse http://localhost:8000) and ensure the audits “Serve images in next‑gen formats” and “Lazy load offscreen images” are passing.

Failure modes

• Large source images (e.g., >5 MB) increase build time significantly because the plugin must generate multiple resized variants for each image.

• If an image URL points to an external, untrusted source, the plugin will fetch it at build time. A malicious payload could compromise the build environment or produce unexpected output.

• Mis‑specified layout props (e.g., using fixed without providing width/height) can cause the plugin to fall back to a single‑size image, losing responsiveness.

Conditions that would change the design

• When image sources become dynamic (e.g., user‑uploaded content at runtime), the build‑time plugin cannot process them; a runtime image‑optimization service or client‑side library would be required.

• If the target audience primarily uses browsers that do not support WebP/AVIF, the plugin’s automatic format conversion may be less beneficial, and you might opt to keep original JPEGs/PNGs.

• When build performance becomes a critical bottleneck (e.g., large monorepo with thousands of images), you might move image processing to a separate CI step or use a CDN‑based image service.