Fixing Images in Next.js

What next/image does and does not do for you

When you render <Image> from next/image, Next.js outputs an ordinary img element whose src and srcset point to its optimisation endpoint, /_next/image, with the original address, a width and a quality in the query string. The first request for each combination is resized and re-encoded on the server, then cached. The component also adds loading="lazy" and decoding="async" by default and requires dimensions so space is reserved.

What it cannot know is how your layout uses the image. It does not read your CSS, so it cannot tell that a card is 300 pixels wide on desktop. That is the job of the sizes prop. It also cannot tell which image is the most important, so it lazy-loads all of them until you mark one as the priority.

The general points about srcset, lazy loading and CDNs are covered in the sibling guides on image dimensions, lazy loading and CDN delivery. This page is about how those map onto Next.js.

The fix, step by step

Configuration and component examples

next.config.js

/** @type {import('next').NextConfig} */
module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
    remotePatterns: [
      { protocol: 'https', hostname: 'cms.example.com', pathname: '/uploads/**' },
    ],
    deviceSizes: [640, 828, 1080, 1280, 1920],
    qualities: [60, 75],
  },
};

Keep the lists short. Every extra width and quality multiplies the number of variants the optimiser may have to produce and cache for each image.

A hero image on a route

import Image from 'next/image';
import hero from '@/public/img/fellside-hero.jpg';

export default function Home() {
  return (
    <Image
      src={hero}
      alt="Walkers on a ridge above Buttermere in autumn"
      sizes="100vw"
      className="hero-img"
      fetchPriority="high"
      loading="eager"
      placeholder="blur"
    />
  );
}

The static import supplies width, height and a blur placeholder. On versions before 16, replace the last two loading props with priority.

A product card using fill

// ProductCard.jsx
<div className="card-media">
  <Image
    src={product.imageUrl}
    alt={product.imageAlt}
    fill
    sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw"
    className="card-img"
  />
</div>

/* styles.css */
.card-media { position: relative; aspect-ratio: 4 / 5; }
.card-img { object-fit: cover; }

A custom loader for an image CDN

// image-loader.js
export default function loader({ src, width, quality }) {
  const q = quality || 75;
  return `https://img.example.com${src}?w=${width}&q=${q}&auto=format`;
}

// next.config.js
module.exports = {
  images: { loader: 'custom', loaderFile: './image-loader.js' },
};

With a custom loader, Next.js still builds the srcset from your configured widths, but each URL points at the CDN, which does the resizing. This is the usual answer for static export and for sites that already pay for an image service.

Hosting differences that affect images

Vercel

Image optimisation is built in and cached at the edge. It is metered, so a site with many remote images, many widths and AVIF enabled uses more than one with a few static images. Narrow remotePatterns and short width lists keep usage predictable. Check the current plan limits in your dashboard rather than assuming.

Self-hosted Node server or container

Recent versions of Next.js use the Sharp library automatically for next start and standalone output. The optimised files are written to .next/cache/images. In containers or on platforms that rebuild the file system on every deployment, that cache is lost, so each variant is regenerated on the first visit after each release. Mount a persistent volume for the cache, or put a CDN in front that respects the long cache headers the optimiser sends.

The images.minimumCacheTTL setting controls how long optimised images are cached when the original has no longer cache header of its own. Next.js 16 raised its default considerably; on older versions it was short enough to cause frequent re-optimisation, so set it explicitly if you are on an older release.

Static export

With output: 'export' the site is plain files with no server to run the optimiser. The build fails for images using the default loader unless you set images.unoptimized to true or configure a custom loader. With unoptimized, the component still reserves space and lazy-loads, but serves your files exactly as they are, so they must already be sized and converted.

Edge cases

• SVG files. Vector images gain nothing from the optimiser. Pass unoptimized for SVGs, or use a plain img. The dangerouslyAllowSVG setting exists but carries security implications for user-supplied files.
• Animated GIFs. Animated images are not resized; they are passed through. Convert long GIFs to short muted videos instead.
• CSS background images. next/image cannot help with these. For a decorative background use CSS with a pre-sized file; for an important one, use a fill image with object-fit: cover behind the content.
• Images from a CMS with its own resizer. If the CMS already serves sized, converted images, running them through the Next.js optimiser as well doubles the work. A custom loader that uses the CMS's own parameters is often simpler.
• Local images with query strings. Recent versions require images.localPatterns to permit query strings on local image paths. If a local image suddenly stops loading after an upgrade, check this.
• Pages Router projects. The same component and settings apply. Older projects may still use next/legacy/image, which wraps images in extra elements; migrating to the current component simplifies styling.

Keeping a Next.js site image-healthy

• Wrap the component. Build a small site-specific image component that requires sizes and a priority flag, so developers cannot forget them.
• Lint for raw img tags. The Next.js ESLint configuration warns about plain img elements. Keep that rule on and justify exceptions in code.
• Review config on upgrades. Image defaults and required settings have changed between major versions. Read the image section of the upgrade guide when moving to a new major release.
• Measure after each release. Run the Image Optimisation audit on your key routes and compare Largest Contentful Paint in field data. For the wider framework picture, see our Core Web Vitals in Next.js guide.