payloadcheck

Find out what is making your API response huge.

One small problem. One obvious API. Very little setup. Immediate value.

You know the endpoint is big:

GET /api/users    2.8 MB

…but not which fields eat the bytes. payloadcheck breaks a payload down by serialized size and tells you exactly where the bulk lives.

Install

npm i payloadcheck

Usage

import { payloadCheck } from "payloadcheck";

payloadCheck(response, { label: "GET /api/users" });

⚠ Large payload: 235.5 KB  (GET /api/users)

Largest fields:

users                235.4 KB  100%
users[]               58.8 KB   25%
users[].avatar        58.6 KB   25%
users[].activity       212 B     0%
meta                    61 B     0%

Possible saving: remove users[]
≈ 25% smaller response

The result also comes back as a plain object when you need it in code:

const analysis = payloadCheck(response, { log: false, warnAboveKb: 256 });
analysis.over;        // true
analysis.kb;          // 235.5
analysis.largest;     // [{ path: "users[].avatar", bytes: 60024, ... }, ...]

Express middleware

import express from "express";
import { payloadCheckMiddleware } from "payloadcheck/middleware";

const app = express();
app.use(payloadCheckMiddleware({ warnAboveKb: 256 }));

CLI

payloadcheck response.json
cat big.json | payloadcheck --label "GET /api/users" --warn-above-kb 128

Prints the critical report and exits with code 2 over the threshold — handy in CI. pack style plain output otherwise: ✓ 18 KB (under the warn threshold).

Next.js style wrapper

import { withPayloadCheck } from "payloadcheck/middleware";

export default withPayloadCheck(handler);

How it works

• serialized-size estimation per JSON.stringify semantics — verified against actual output in tests
• recursive subtree breakdown (users[].avatar)
• biggest-field ranking with share of total
• warning threshold with clean exit codes for CI
• zero runtime dependencies, ESM + CJS + .d.ts + CLI bin

Node >= 18.

License

MIT