How I cut a 1.1 GB image gallery to 30 MB without touching a single database row

Prompt Pin — Sun, 02 Aug 2026 14:12:15 +0000

I run a small AI-photo-prompt gallery — a few hundred prompts, each with an example image. It started as a weekend project and grew faster than the infrastructure did. By the time I looked properly, the images directory was 1.1 GB across 2,650 files, and a single gallery page was shipping 2–3 MB of images to phones on Indian mobile data.

This is the writeup of getting that under control, and the three things that surprised me along the way — including one bug that cost me an hour and had nothing to do with images at all.

The measurement that reframed the problem

My first instinct was "the JPEGs are too big, crank the compression." I was wrong. The actual breakdown:

Format	Files	Total	Avg
PNG	1,541	892 MB	593 KB
JPEG	1,057	119 MB	115 KB

PNG was 58% of the files but 75% of the bytes. Same photos, 5× the weight — because whatever generated these exported PNG by default, and PNG is lossless, designed for logos and screenshots, not photographs.

The dimensions were fine (typical image ~830×1250). This wasn't oversized images. It was pure format waste.

Converting to WebP at quality 82:

423.7 MB  →  29.8 MB   (93% reduction)

A 4 MB PNG became a 126 KB WebP. On the actual prompt pages — the ones that get search traffic — the hero image went from 668 KB to 68 KB (89%).

Surprise #1: don't trust a size metric, look at the pixels

RMSE (root-mean-square error vs the original) flagged two images as "possibly degraded" at q82. Before mass-converting a few hundred irreplaceable images, I generated 100%-zoom side-by-side crops of the busiest region of each and actually looked.

They were fine. The high RMSE came from high-saturation graphic content — bold colour patterns inflate the metric without any visible degradation. If I'd trusted the number, I'd have wasted 30% more bytes bumping the quality for no visible gain.

Lesson: for lossy image work, a perceptual eyeball on the worst cases beats any single scalar metric. q82 turned out to be the sweet spot — indistinguishable from the original, including on smooth gradients where banding shows first.

The design decision: `<picture>`, not replacement

Here's the part I'm most glad I got right. I did not convert PNG→WebP in place, and I did not rewrite any image URLs in the database.

Instead I generated a sibling file next to each original:

foo.png        (untouched)
foo.png.webp   (new, generated)

And served them with a plain <picture> element:

<picture>
  <source srcset="/images/foo.png.webp" type="image/webp">
  <img src="/images/foo.png" width="832" height="1248" loading="lazy">
</picture>

Why this shape matters:

Zero database writes. The image URLs in my DB (and in the mobile app's API that reads the same DB) never changed. Rewriting hundreds of URLs risked breaking the app's response contract for no benefit.
Automatic fallback. Any client that can't do WebP gets the original. No feature detection, no JS.
Rollback is rm. find . -name '*.webp' -delete and the code no-ops itself, because it only emits <picture> when a sibling exists.
Adding width/height fixed layout shift (CLS) for free while I was in there.

The originals were never modified, renamed, or deleted. The worst case for the whole operation was "wasted disk," not "lost data" — which is the failure mode you want when touching hundreds of files you can't regenerate.

Surprise #2: I was double-wrapping every image

My gallery HTML is produced by a shortcode, and that shortcode's output flows through two filters — the shortcode filter itself, and the general content filter. My guard checked whether the <img> tag was already wrapped... but by the second pass, the <picture> wrapper was outside the tag, so the regex matched the bare <img> again and wrapped it a second time.

Result: 48 <picture> elements for 26 images. Nested <picture> is invalid HTML.

The fix was a data- marker stamped on tags the first pass had already handled, so the second pass skips them. Obvious in hindsight; invisible until I counted the tags in the rendered output. Which is the real lesson — count the elements in the actual response, don't assume your filter ran once.

Surprise #3: the bug that wasn't about images at all

This one cost the most time. On the pages I render with a custom document template, the site nav suddenly rendered centred instead of right-aligned — but only on those pages.

I diffed the markup against a working page. Byte-identical. Same container classes, same is-content-justification-right. The HTML was correct.

What was missing was the CSS defining those classes. A working page emitted 7 layout rules; my custom page emitted zero. The specific casualty:

.wp-container-...-is-layout-46c2b0f2 { justify-content: flex-end; }

The cause: this CSS framework collects block layout styles while blocks render, then flushes them into <head>. My template called the head-flush first and rendered the header afterwards — so by the time the header produced its container classes, the stylesheet had already been sent. The classes existed in the DOM with nothing defining them.

Fix: render the header and footer into buffers before flushing the head, then echo them. Styles get registered in time.

The general lesson has stuck with me: when markup is identical but rendering differs, stop looking at the markup. The difference is somewhere in the pipeline — order of operations, a style registry, a hook that didn't fire — not in the HTML you keep re-reading.

Results

Image payload on the pages that matter: ~90% smaller
No database changes, so the companion mobile app was completely unaffected
Fully reversible at every layer
The originals sit untouched on disk, plus a verified full backup, because you do not mass-process irreplaceable files without a tested restore path

If you're doing something similar

A few things I'd tell myself at the start:

Measure format distribution before compression settings. My whole win was "PNG photos are the problem," not "quality is too high."
Convert alongside, serve with <picture>, never rewrite URLs. It makes the whole thing reversible and keeps any downstream API consumers oblivious.
Eyeball the worst cases at 100%. One perceptual check beats a directory of RMSE numbers.
Count elements in the rendered output. Both my real bugs — double-wrapping and missing CSS — were invisible in the source and obvious the moment I counted what actually shipped.

The gallery this came from is PromptPin — a searchable set of copy-paste AI photo prompts, each shown with its example image. Built on WordPress with a separate prompts database and a custom gallery plugin, which is a whole other writeup. Happy to go deeper on any of the above in the comments.

DEV Community: Prompt Pin