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
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
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.jsonnext to this article. - The script above, unchanged, run with
nodefromapps/web/publiconimagesand onimages/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.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.