Next.js Image Optimization

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.