Fix LCP in Gatsby: Optimize Largest Contentful Paint in 2026

Gatsby ships with a powerful image processing pipeline, yet Largest Contentful Paint scores above 4 seconds are common on freshly scaffolded Gatsby sites. The root cause is almost always the same: the deprecated gatsby-image package still in use, a hero image served as a plain img tag, or the modern gatsby-plugin-image component left in its lazy-loading default for an above-the-fold element. Gatsby's static site generation already eliminates server-side rendering delay from TTFB, which gives it a structural advantage over SSR frameworks. Squandering that advantage on an unoptimized hero image is the single most common performance regression on Gatsby projects. This guide walks through five concrete, measurable fixes — from migrating to gatsby-plugin-image and configuring AVIF output, to injecting preload links in the document head and delegating image processing to a custom CDN for large sites with thousands of pages. Following all five steps consistently brings LCP from the poor range into the good range in a single build.

Expected results

The metrics below reflect a Gatsby 5.13 marketing site with a 1,200 x 630 hero image, measured with Lighthouse 12 on a simulated 4G connection (10 Mbps down, 40ms RTT) from a Netlify CDN edge node. Your numbers will vary based on image size, hosting, and page weight, but the relative gains are representative.

Common causes of poor LCP in Gatsby

Before reaching for fixes, it is worth understanding why Gatsby sites underperform on LCP despite generating static HTML at build time. The static HTML delivery advantage is real — TTFB on a CDN-hosted Gatsby site is typically under 100ms — but that advantage disappears if the LCP element is not in the initial HTML payload or is deprioritized by the browser.

• Using the deprecated gatsby-image package. The original gatsby-image was deprecated in Gatsby 3. It ships no AVIF support, uses a different GraphQL fragment schema, and lacks the loading and fetchpriority props that modern browsers rely on for resource scheduling. Projects that scaffolded before 2022 frequently still have the old package installed alongside the new one, creating confusion about which component is actually rendering.
• Leaving loading="lazy" as the default on the hero. Both GatsbyImage and StaticImage default to lazy loading. For images below the fold this is correct, but for the largest visible element on the first viewport it adds 200-600ms of latency while the browser waits for the JavaScript bundle to hydrate and trigger the intersection observer before starting the image fetch.
• No preload link in the document head. Even with loading="eager", the browser cannot discover the image URL until React renders the component tree. A rel=preload tag injected during the Gatsby build allows the browser to begin fetching the image during HTML parsing, before any JavaScript executes.
• Serving JPEG or PNG instead of AVIF or WebP. AVIF images are typically 40-60% smaller than equivalent-quality JPEG files. On a 4G connection, a 300KB hero JPEG takes roughly 240ms to transfer. The equivalent AVIF at 120KB takes under 100ms. That 140ms difference alone can be the margin between a good and needs-improvement LCP score.
• Image art direction serving oversized assets on mobile. A 1,200px-wide desktop hero image delivered unchanged to a 390px-wide phone screen wastes bandwidth on pixel data that is never displayed. Without withArtDirection and a properly tuned sizes attribute, mobile LCP is consistently worse than desktop.
• Build-time image processing blocking incremental builds on large sites. Sites with 5,000+ pages and images frequently disable image optimization entirely because build times become unacceptable. Moving to a custom image CDN restores optimization without the build-time cost.

Step-by-step fix

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

// gatsby-config.js
module.exports = {
  plugins: [
    "gatsby-plugin-image",
    {
      resolve: "gatsby-plugin-sharp",
      options: {
        // Generate AVIF by default, with WebP and original as fallbacks
        defaults: {
          formats: ["auto", "webp", "avif"],
          placeholder: "blurred",
          quality: 80,
          breakpoints: [360, 480, 768, 1024, 1280, 1536],
          backgroundColor: "transparent",
        },
      },
    },
    "gatsby-transformer-sharp",
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "images",
        path: `${__dirname}/src/images`,
      },
    },
  ],
};

// Before: plain img tag, no optimization, lazy by default
import React from "react";

export function Hero() {
  return (
    <section className="hero">
      <img
        src="/images/hero.jpg"
        alt="Dashboard overview"
        className="hero__image"
      />
    </section>
  );
}

// After: StaticImage with AVIF output, eager loading, and high fetchpriority
import React from "react";
import { StaticImage } from "gatsby-plugin-image";

export function Hero() {
  return (
    <section className="hero">
      <StaticImage
        src="../images/hero.jpg"
        alt="Dashboard overview"
        layout="fullWidth"
        loading="eager"
        fetchpriority="high"
        formats={["auto", "webp", "avif"]}
        quality={85}
        placeholder="blurred"
        className="hero__image"
      />
    </section>
  );
}

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

export default function BlogPost({ data }) {
  const coverImage = getImage(data.markdownRemark.frontmatter.cover);

  return (
    <article>
      <GatsbyImage
        image={coverImage}
        alt={data.markdownRemark.frontmatter.coverAlt}
        loading="eager"
        fetchpriority="high"
        className="post-cover"
      />
      <h1>{data.markdownRemark.frontmatter.title}</h1>
    </article>
  );
}

export const pageQuery = graphql`
  query BlogPostQuery($slug: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {
      frontmatter {
        title
        coverAlt
        cover {
          childImageSharp {
            gatsbyImageData(
              layout: FULL_WIDTH
              formats: [AUTO, WEBP, AVIF]
              quality: 85
              placeholder: BLURRED
              breakpoints: [360, 768, 1280]
            )
          }
        }
      }
    }
  }
`;

npm install gatsby-plugin-preload-link-crossorigin

// gatsby-config.js — add to plugins array
{
  resolve: "gatsby-plugin-preload-link-crossorigin",
  options: {
    // Optional: scope preloading to specific pages
    cachePublicFolder: true,
  },
},

// gatsby-ssr.js
const React = require("react");

exports.onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <link
      key="hero-preload"
      rel="preload"
      as="image"
      href="/static/hero-1280.avif"
      imagesrcset="/static/hero-360.avif 360w, /static/hero-768.avif 768w, /static/hero-1280.avif 1280w"
      imagesizes="100vw"
      fetchpriority="high"
      crossOrigin="anonymous"
    />,
  ]);
};

import React from "react";
import { graphql } from "gatsby";
import { GatsbyImage, getImage, withArtDirection } from "gatsby-plugin-image";

export default function HeroSection({ data }) {
  const images = withArtDirection(
    // Default: desktop image (used for viewports >= 768px)
    getImage(data.desktopImage),
    [
      {
        // Override: portrait crop for phones
        media: "(max-width: 767px)",
        image: getImage(data.mobileImage),
      },
    ]
  );

  return (
    <section className="hero">
      <GatsbyImage
        image={images}
        alt="Platform dashboard — responsive hero"
        loading="eager"
        fetchpriority="high"
        className="hero__image"
      />
    </section>
  );
}

export const query = graphql`
  query HeroQuery {
    desktopImage: file(relativePath: { eq: "hero-desktop.jpg" }) {
      childImageSharp {
        gatsbyImageData(
          layout: FULL_WIDTH
          formats: [AUTO, WEBP, AVIF]
          quality: 85
          breakpoints: [1024, 1280, 1536]
        )
      }
    }
    mobileImage: file(relativePath: { eq: "hero-mobile.jpg" }) {
      childImageSharp {
        gatsbyImageData(
          layout: FULL_WIDTH
          formats: [AUTO, WEBP, AVIF]
          quality: 85
          breakpoints: [360, 480, 768]
        )
      }
    }
  }
`;

# On Gatsby Cloud, set this environment variable in the site dashboard
# or in your CI environment
GATSBY_CLOUD_IMAGE_CDN=1

npm install gatsby-transformer-cloudinary gatsby-source-cloudinary

// gatsby-config.js
require("dotenv").config();

module.exports = {
  plugins: [
    "gatsby-plugin-image",
    {
      resolve: "gatsby-transformer-cloudinary",
      options: {
        cloudName: process.env.CLOUDINARY_CLOUD_NAME,
        apiKey: process.env.CLOUDINARY_API_KEY,
        apiSecret: process.env.CLOUDINARY_API_SECRET,
        // Upload local images to Cloudinary at build time
        uploadFolder: "gatsby-site",
        // Use Cloudinary's f_auto,q_auto transformation for format negotiation
        transformations: ["f_auto", "q_auto"],
        // Generate AVIF via f_avif for supporting browsers
        overwriteExisting: false,
      },
    },
    {
      resolve: "gatsby-source-cloudinary",
      options: {
        cloudName: process.env.CLOUDINARY_CLOUD_NAME,
        apiKey: process.env.CLOUDINARY_API_KEY,
        apiSecret: process.env.CLOUDINARY_API_SECRET,
        resourceType: "image",
        prefix: "gatsby-site/",
        maxResults: 500,
      },
    },
  ],
};

# .env.production
# Enable the LMDB data store for persistent build caching
GATSBY_EXPERIMENTAL_LMDB_STORE=1
# Increase Node.js heap for large image processing jobs
NODE_OPTIONS=--max-old-space-size=4096

Verification

After implementing all five steps, measure LCP using both lab tools and field data. Lab tools give you immediate feedback during development; field data from real users is the signal Google actually uses for Core Web Vitals ranking.

Lab measurement

Run a Lighthouse audit from Chrome DevTools (Lighthouse tab, Mobile preset, Simulated throttling) after a production build. Gatsby development mode bypasses image optimization, so always measure a built and served site, not gatsby develop. Use gatsby build && gatsby serve locally, or push to a preview deployment and measure there.

In the Lighthouse report, check three things: the LCP element identified in the Diagnostics section (should be your hero image, not a text node), the LCP time breakdown showing a short load delay and short render delay, and the "Largest Contentful Paint image was not lazily loaded" audit passing.

WebPageTest at webpagetest.org provides a filmstrip view that makes it easy to see exactly when the hero image first appears on screen. Run the test from the Dulles, Virginia node on a Moto G4 profile (which mirrors Chrome's lab condition). Compare the filmstrip frame where the hero becomes visible to the total page load time.

Field measurement with CrUX

Chrome User Experience Report (CrUX) data is available with a 28-day lag through PageSpeed Insights at pagespeed.web.dev. After deploying your Gatsby optimizations, check back in 4 weeks to see the field LCP distribution shift. The 75th percentile is the threshold Google uses for Core Web Vitals pass/fail status in Search Console.

Enable Web Vitals reporting in your Gatsby site using the gatsby-plugin-web-vitals package or a manual implementation. This sends CWV data to your analytics platform on every page load, giving you real-user LCP distributions broken down by page path, device type, and network speed.

// gatsby-browser.js
export function onRouteUpdate() {
  if (typeof window === "undefined") return;

  import("web-vitals").then(({ onLCP, onCLS, onINP }) => {
    const sendToAnalytics = (metric) => {
      // Replace with your analytics endpoint or gtag call
      if (window.gtag) {
        window.gtag("event", metric.name, {
          event_category: "Web Vitals",
          event_label: metric.id,
          value: Math.round(
            metric.name === "CLS" ? metric.value * 1000 : metric.value
          ),
          non_interaction: true,
        });
      }
    };
    onLCP(sendToAnalytics);
    onCLS(sendToAnalytics);
    onINP(sendToAnalytics);
  });
}

Quick checklist

Common pitfalls

• Applying eager loading to multiple images. Setting loading="eager" on every above-the-fold image cancels out the benefit. The browser treats all eager images equally, which can hurt LCP by splitting bandwidth and fetch priority across multiple requests. Apply fetchpriority="high" only to the single largest visible element. All other images should retain the default lazy loading behavior.
• Measuring in gatsby develop mode. Development mode disables most image optimization, serves full-resolution JPEGs, and skips the build-time preload injection. LCP measurements from development are misleading and typically 2-3x worse than production. Always run gatsby build && gatsby serve before taking Lighthouse measurements.
• Forgetting to update GraphQL queries after migration. After removing gatsby-image, any remaining GatsbyImageSharpFluid or GatsbyImageSharpFixed fragment references will throw a GraphQL error at build time. Run gatsby build locally and check the terminal output for fragment errors before deploying.
• Setting quality too high for AVIF. AVIF's perceptual quality curve is different from JPEG's. AVIF at quality 85 produces output that is visually equivalent to JPEG at quality 95, and is typically 50% smaller. Setting AVIF quality above 85 produces files nearly as large as JPEG with no perceptible visual benefit. The default quality: 80 in gatsby-plugin-sharp is a reasonable starting point for most photography.
• Not testing on real mobile hardware. Lighthouse's mobile simulation uses CPU throttling to approximate a mid-range Android phone, but real devices have additional constraints around GPU memory, thermal throttling, and network variability. Test your optimized Gatsby site on at least one physical Android device using Chrome DevTools remote debugging before considering LCP work complete.

Frequently asked questions