Decision Guide: gatsby-plugin-image vs Legacy gatsby-image in Gatsby

Decision and Constraints

For new Gatsby projects, adopt gatsby-plugin-image as the image optimization solution. This decision assumes you are using Gatsby v2.24.0 or later, React 16.8+ (to support hooks), and you can modify gatsby-config.js. The legacy gatsby-image plugin is deprecated and lacks newer features such as built‑in lazy loading with IntersectionObserver and React 18 concurrent‑mode support.

Comparison Table

Feature	gatsby-plugin-image	Legacy gatsby-image
Automatic resizing (via Sharp)	Yes	Yes
Modern formats (WebP, AVIF)	Yes, configurable	Yes, but requires extra plugins
Lazy loading with IntersectionObserver	Built‑in	Requires gatsby-plugin-loadable-components or manual setup
React 18 concurrent‑mode support	Yes	No
Bundle impact (gzipped)	~2 KB	Larger due to legacy code
Documentation status	Actively maintained	Deprecated (no new features)

Trade‑offs

• Advantages of gatsby-plugin-image: smaller bundle, built‑in lazy loading, native WebP/AVIF support, compatible with React 18 concurrent mode, actively maintained.
• Limitations of legacy gatsby-image: larger bundle, needs additional plugins for modern formats and lazy loading, no concurrent‑mode support, deprecated.
• When legacy might still be used: existing projects locked to older Gatsby versions where upgrading would break other dependencies, or when a custom Sharp pipeline is already in place.

Implementation

Add the plugin to gatsby-config.js:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-image',
      options: {
        formats: ['auto', 'webp', 'avif'],
        // optional: placeholder styles, background color, etc.
      },
    },
    // other plugins...
  ],
};

Then use it in a component:

import React from 'react';
import { GatsbyImage, getImage } from 'gatsby-plugin-image';

export default function ImageDemo({ data }) {
  const image = getImage(data.file.childImageSharp);
  return (
    
  );
}

Verification

1. Run gatsby develop. Open Chrome DevTools → Network, filter by img. Confirm that requests include width parameters (e.g., ?w=800) and end with .webp or .avif.
2. Run gatsby build. Inspect public/_next/static/media/ (or public/static/ depending on your Gatsby version) for multiple sized files such as image-800w.webp, image-1600w.webp.
3. Run a Lighthouse audit (Performance → Properly sized images). The opportunity score should improve compared to a baseline using the legacy plugin.

Rollback (if needed)

To revert to the legacy plugin:

1. Remove gatsby-plugin-image from gatsby-config.js and delete its options.
2. Add gatsby-image (and any required format plugins) back to the plugins array.
3. Replace component imports: import { Img } from 'gatsby-image' and usage accordingly.
4. Run gatsby clean then gatsby develop to verify the legacy behavior.