Pixel-by-pixel Comparison in Vanilla JavaScript
@blazediff/core counts the pixels that differ between two images, in pure
JavaScript. No native binary, no WebAssembly, no install step beyond npm install. It runs anywhere JS runs and it is API-compatible with
pixelmatch , so switching is a one-line
import change.
Reach for it when portability matters more than raw throughput: a browser bundle, a Deno script, a serverless function where you would rather not ship a binary. When throughput is what matters, the same algorithm is available compiled: WebAssembly for the browser and the edge, Node native for CI.
Installation
npm install @blazediff/coreExamples
You supply decoded RGBA data. loadImage below is whatever decoder your runtime
already has: a canvas in the browser, @blazediff/codec-pngjs or sharp on the
server.
Basic Comparison
Image 1
Image 2
Result
import blazediff from "@blazediff/core";
// loadImage can either be a browser function or a server function
const img1 = await loadImage(
"https://raw.githubusercontent.com/teimurjan/blazediff/refs/heads/main/fixtures/blazediff/3a.png"
);
const img2 = await loadImage(
"https://raw.githubusercontent.com/teimurjan/blazediff/refs/heads/main/fixtures/blazediff/3b.png"
);
const output = new Uint8Array(img1.width * img1.height * 4);
const width = img1.width;
const height = img1.height;
// Returns the number of differing pixels and fills `output` with the diff image.
const diff = blazediff(img1, img2, output, width, height);Pass null instead of an output buffer when you only need the count. That skips
writing the diff image, which is the more expensive half of the work.
What it costs
Measured against pixelmatch on the same fixtures, decode excluded, M1 Max, Node 22, 50 iterations:
| Case | pixelmatch | @blazediff/core |
|---|---|---|
| 4K pair, count only | 201.60-253.77ms | 96.52-135.89ms |
| 4K pair, identical | 23.79-28.04ms | 2.50-3.77ms |
| 4K pair, writing a diff image | 280.79-336.93ms | 151.72-205.21ms |
Averaged over the whole fixture set that is ~62% faster when counting and ~28% faster when also rendering a diff image. Small images narrow the gap further: the win comes from skipping unchanged blocks, and there are fewer of them to skip. Full tables.
Next
- Same algorithm, 5x to 10x faster on 4K: WebAssembly or Node native
- Exact matching too strict? Structural comparison
- Every option and its default:
@blazediff/corereference