Next.js Image Optimization

Serve optimized, correctly sized images automatically with next/image

When to Use

• Displaying images in any Next.js page or component
• Improving Core Web Vitals (LCP, CLS) by preventing layout shift and lazy loading images
• Serving modern formats (WebP, AVIF) without manual conversion
• Building responsive images that adapt to viewport and container size
• Loading above-the-fold images with priority to improve LCP score

Instructions

1. Import

   Image

   from

   next/image

   instead of the HTML

   <img>

   tag for all content images.
2. Always provide

   width

   and

   height

   props for images with known dimensions to prevent layout shift (CLS).
3. Use

   fill

   prop with a positioned parent (

   position: relative

   ) for images that should fill their container — omit

   width

   and

   height

   when using

   fill

   .
4. Add

   priority

   to the first image visible in the viewport (the LCP element) to disable lazy loading and preload it.
5. Use the

   sizes

   prop to tell the browser how wide the image will be at each breakpoint — this enables accurate

   srcset

   selection.
6. Add remote domains to

   images.remotePatterns

   in

   next.config.ts

   before using external image URLs.
7. Use

   placeholder="blur"

   with

   blurDataURL

   for a low-quality preview while the image loads.
8. For static imports, Next.js generates

   blurDataURL

   automatically —

   import logo from './logo.png'

   and pass the imported object.

// next.config.ts
const config = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.example.com', pathname: '/images/**' },
    ],
  },
};

// app/products/[id]/page.tsx
import Image from 'next/image';
import heroImage from '@/public/hero.jpg'; // static import — dimensions known

export default function ProductPage() {
  return (
    <div>
      {/* Static import — auto blur placeholder, auto width/height */}
      <Image src={heroImage} alt="Hero" priority placeholder="blur" />

      {/* Remote image — fill mode for responsive container */}
      <div className="relative h-64 w-full">
        <Image
          src="https://cdn.example.com/images/product.jpg"
          alt="Product"
          fill
          sizes="(max-width: 768px) 100vw, 50vw"
          className="object-cover"
        />
      </div>
    </div>
  );
}

Details

next/image

wraps the HTML

<img>

element with automatic size optimization, format conversion, and lazy loading. The optimization pipeline runs server-side: Next.js resizes and converts images to WebP or AVIF on first request and caches the result.

sizes

attribute importance: Without

sizes

, the browser assumes the image is

100vw

wide and downloads a larger source than necessary. Providing accurate

sizes

(e.g.,

"(max-width: 640px) 100vw, 640px"

) reduces bandwidth significantly.

fill mode: Use

fill

when the image dimensions are unknown or when the image should fill a CSS-controlled container. The parent must have

position: relative

(or

absolute

/

fixed

). Use

className="object-cover"

or

className="object-contain"

on the Image to control aspect ratio.

priority vs lazy: All images are lazy-loaded by default (loaded when they enter the viewport). The

priority

prop disables lazy loading and adds a

<link rel="preload">

— use it for the LCP image only. Adding

priority

to multiple images defeats its purpose.

Layout shift (CLS): Providing

width

and

height

lets the browser reserve space before the image loads, preventing layout shift. The

fill

prop avoids this by letting CSS control the container dimensions.

Remote patterns: The

remotePatterns

config (replacing the deprecated

domains

) supports wildcards and pathnames. Misconfigured patterns cause 400 errors on image optimization requests.

Source

https://nextjs.org/docs/app/api-reference/components/image

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.