Dev.to WebDev 🛠 Dev 👁 0 📖 4 min read

Fail CI when an image is over its byte budget (Node script)

A byte budget for images is a small script that walks a folder, compares each file to a limit for its format, and exits with code 1 when any file is over. CI treats a non-zero exit as a failed check. We ran ours on a rea

Fail CI when an image is over its byte budget (Node script)

A byte budget for images is a small script that walks a folder, compares each file to a limit for its format, and exits with code 1 when any file is over. CI treats a non-zero exit as a failed check. We ran ours on a real 1,585-image folder: it flagged 24 files and the total was 85,778,075 bytes against a 12,000,000 byte budget.

Why check bytes in CI at all?

Nobody reviews a binary diff. A reviewer sees "Bin 0 -> 9804300 bytes" and approves. One camera photo committed straight from a phone is 9.8 MB, and it ships to every visitor until someone notices.

A budget turns that into a failing check on the pull request. The rule is written down, so the argument happens once, in a config, not in every review.

What does the script look like?

It needs no dependencies. It walks the tree with readdir, reads each size with stat, and compares it to a limit chosen by extension. We picked 250,000 bytes for JPEG, 300,000 for PNG, 150,000 for WebP and AVIF, and 12,000,000 for the whole folder. These are our numbers, not a standard. Pick yours from your own pages.

// check-image-budget.mjs: fail CI when an image is over its byte budget.
import { readdir, stat } from 'node:fs/promises';
import { join, extname } from 'node:path';

const root = process.argv[2] ?? 'public/images';
const BUDGET = { '.jpg': 250_000, '.jpeg': 250_000, '.png': 300_000, '.webp': 150_000, '.avif': 150_000 };
const TOTAL = 12_000_000;

async function* walk(dir) {
  for (const e of await readdir(dir, { withFileTypes: true })) {
    const p = join(dir, e.name);
    if (e.isDirectory()) yield* walk(p);
    else yield p;
  }
}

let total = 0, checked = 0;
const over = [];
for await (const file of walk(root)) {
  const limit = BUDGET[extname(file).toLowerCase()];
  if (!limit) continue;
  const { size } = await stat(file);
  checked++;
  total += size;
  if (size > limit) over.push({ file, size, limit });
}

over.sort((a, b) => b.size - a.size);
for (const o of over) console.log(`FAIL ${o.file}  ${o.size} bytes (limit ${o.limit}, over by ${o.size - o.limit})`);
console.log(`${checked} images, ${total} bytes total (budget ${TOTAL}), ${over.length} over their limit`);
if (total > TOTAL) console.log(`FAIL total over by ${total - TOTAL} bytes`);
process.exit(over.length > 0 || total > TOTAL ? 1 : 0);

Two details matter. The script sorts offenders by size, so the worst file is the first line of the log. And it sets the exit code explicitly: a script that only prints "FAIL" still passes CI.

What did it print on a real folder?

We ran it on the image folder of this site (apps/web/public/images). The first lines:

FAIL images/index/image-compressor-sample-camera-photo.jpeg  9804300 bytes (limit 250000, over by 9554300)
FAIL images/convert/heic-to-png-converter-result.png  997215 bytes (limit 300000, over by 697215)
FAIL images/tools/crop-png-online-result.png  705491 bytes (limit 300000, over by 405491)
FAIL images/convert/webp-sample-photo-original.webp  611228 bytes (limit 150000, over by 461228)
...
1585 images, 85778075 bytes total (budget 12000000), 24 over their limit
FAIL total over by 73778075 bytes

The four largest files over budget, led by a 9,804.3 KB camera photo

Most of those files are deliberate. This folder holds the original photos that our tool pages compress, so they are big on purpose. That is the point of a budget: it forces a choice. You raise the limit for a named file, or you shrink the file.

A smaller folder shows the passing case. images/pricing has one image:

1 images, 9736 bytes total (budget 12000000), 0 over their limit

The exit code was 0.

How do you run it in CI?

Any CI runs a command and reads its exit code. Here is a GitHub Actions job. We did not run this workflow file; we ran the script it calls.

name: image-budget
on: pull_request
jobs:
  budget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: node scripts/check-image-budget.mjs public/images

Check the current action versions in GitHub's docs before you copy this.

How do you handle files you cannot shrink?

Add an allowlist: a map from path to a higher limit, with a comment saying why. Keep it in the repo so it shows up in review. Do not raise the global limit to fit one file.

Note: Check the bytes the user downloads, not the bytes in git. If your build resizes or converts images, run the check on the build output folder too. A source file at 9.8 MB can be fine if the build emits a 173 KB variant, and a small source can still become a large output.

If a file fails, our guide on reducing image file size covers the fixes in order of effort, and the pre-commit hook approach in our other article catches the file before it reaches CI.

How I measured

  • Date: 2026-10-18. Machine: Apple M1 Pro, macOS 15.7.3.
  • Node 24.22.0, sharp 0.35.4, libvips 8.18.6.
  • KB = 1,000 bytes. Raw numbers are in measured.json next to this article.
  • The script above, unchanged, run with node from apps/web/public on images and on images/pricing.

What I did not test

I did not run the GitHub Actions workflow. I did not check dimensions or pixel counts, only bytes.

I build Blinkimg, an image compressor and converter with a developer API. I wrote this article with help from an AI assistant (Claude), which ran the code on my machine; every number in it comes from those runs.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.