Catch Oversized Images Before They Ship: Image Audits in CI

·5 min read

Oversized images — files downloaded far larger than the box they render into — are the most common image-performance mistake on the web. We measured 44 popular sites and found 68% ship at least one. The reason they persist is simple: they are invisible in normal workflows. The image looks fine. Nobody notices until a performance audit months later. The fix is to move the check to where regressions happen — your pipeline.

The one-liner

Scan any deployed URL from the command line. No local browser needed — the scan runs server-side:

npx imagedimensions-cli https://example.com

You get every image's natural vs. rendered size, the overshoot ratio, and the format breakdown:

⚠ https://example.com
  58 images (41 visible) · 7% WebP/AVIF · 9/37 oversized (≥4× area)
      102.0×  4000x3000 → 400x300  [jpg]  https://example.com/hero.jpg
       18.4×  1600x1200 → 372x279  [png]  https://example.com/card.png
  report: https://imagedimensions.com/results?scanId=…

Make it a gate

Add --max-oversized 0 and the command exits non-zero if any image is oversized — so it fails the build instead of just printing a warning:

npx imagedimensions-cli "$DEPLOY_URL" --max-oversized 0

Tune the strictness with --threshold (the area-overshoot ratio that counts as oversized; default 4, roughly 2× per dimension — already beyond a retina allowance). Raise --max-oversized if you want to allow a small budget rather than zero.

As a GitHub Action

Fail a pull request the moment a preview deploy ships an oversized image:

# .github/workflows/image-audit.yml
name: Image audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: Bishop81/[email protected]
        with:
          url: https://staging.example.com
          max-oversized: '0'

Need it scriptable?

Add --json for machine-readable output you can pipe into a dashboard, a PR comment, or your own thresholds:

npx imagedimensions-cli https://example.com --json | jq '.reports[].oversizedCount'

There is also an interactive scanner if you want the visual report, and an MCP server (imagedimensions-mcp) so AI coding agents can run the same audit during development.

Then fix what it finds

Once CI is catching regressions, the remediation is mechanical: right-size to the display dimensions, add srcset, and convert to a modern format with the client-side PNG→WebP and JPG→WebP converters. The full workflow is in this writeup.

Want the visual version first? Scan any URL in the browser.

Run a free scan →

Related reading