Turning on next.js images unoptimized looks like a mistake in a code review—and in our own next.config.ts, it’s exactly what we did, with a comment so nobody reverts it. Our covers were getting softer on mobile, and the culprit was stacking two lossy encoders. Here’s when that config is correct, when it’s dangerous, and how to document it so the next developer doesn’t “fix” it.

When next.js images unoptimized is the correct call

The safe time to set images.unoptimized is when your upstream source already delivers a well‑sized, modern‑format image. In our case, Payload CMS re‑encodes every upload to WebP once, at upload time. Next.js’s <Image> component then wanted to run its own lossy transformation on top of that already‑lossy WebP. The result: double encoding that visibly softened photographic covers on mobile.

Turning the optimizer off let the CMS‑encoded WebP serve as‑is. The covers got sharper immediately. The config that made it happen lives in the repo with a comment that explains the trade‑off:

// next.config.ts
images: {
  unoptimized: true, // Payload already encodes to webp at upload;
                     // Next's optimizer was re-encoding and softening images.
                     // Keep off.
}

The broader rule is simple: image optimization is not additive. Each lossy pass compounds the artifacts of the previous encode. If something upstream already produced a compressed, correctly sized image in a modern format (WebP, AVIF), a second optimizer is not making it better—it’s re‑encoding the artifacts of the first encode. Know how many lossy passes your pipeline runs before you let Next.js add another one.

When you must keep Next.js image optimization enabled

Keep Next.js’s optimizer on when you are serving original‑quality uploads—untouched JPEGs, PNGs, or even large TIFFs that come straight from a user’s camera or a design tool. Those files are almost never ready for the web. The optimizer generates responsive srcset variants across multiple viewport widths, converts to modern formats when the browser supports them, and compresses the output—all without you building a media pipeline.

You also need the default optimizer when your source images are not already correctly sized. If your CMS just stores whatever the editor uploaded, turning unoptimized on means you’ll be serving 4000‑pixel‑wide hero shots in a 300‑pixel card. That’s a performance disaster.

Finally, remember that images.unoptimized is a global flag. Once you flip it, you assume responsibility for dimensions, format, and art direction. If your CMS doesn’t handle that, you’ve simply removed optimization rather than avoided duplication. A naive reading of this article will make somebody’s site worse—make sure your pipeline is actually doing the job before you reach for the off switch.

On Vercel, image optimization is a billed transformation. Turning it off where it adds nothing removes a cost line as well as a quality problem. That’s a nice side effect, but quality was our primary driver. Don’t let the cost tail wag the quality dog.

How to configure next.js images unoptimized (and why it needs a comment)

The configuration itself is a single key in next.config.js or next.config.ts:

module.exports = {
  images: {
    unoptimized: true,
  },
}

That’s it. But without context, it reads like a lazy shortcut. Any developer—or a future you—will see it and wonder if it was left over from a debug session. A comment transforms it from a potential bug into a documented decision. Ours spells out the CMS workflow, the double‑encoding problem, and the quality improvement. If you’re adopting this pattern, steal that format.

If you need more granular control (e.g., bypassing optimization only for images from a specific CDN), you’ll have to build a custom loader. The global flag is intentionally blunt. For most sites where the CMS already handles the heavy lifting, that bluntness is a feature—it keeps the pipeline simple and predictable.

*