shapedrift

Know when your API response changes before your frontend breaks.

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

Backend responses drift. Nothing tells you until a page breaks in production. OpenAPI, Zod and contract testers solve this — with ceremony. shapecheck (the npm command of shapedrift) gives you the middle ground: a snapshot of your API's shape, and a diff when it drifts.

Install

npm i shapedrift

Usage

import { shapecheck } from "shapedrift";

shapecheck("user", response);

first run    ✓ user — shape recorded
unchanged    ✓ user unchanged
drifted      ⚠ API SHAPE CHANGED — possibly breaking

Snapshot file .shapecheck/user.json:

{
  "label": "user",
  "updatedAt": "2026-09-28T11:28:14.876Z",
  "shape": {
    "id": "number",
    "name": "string",
    "profile": {
      "avatar": "null",
      "city": "string"
    },
    "roles": ["string"]
  }
}

Drift example:

⚠ API SHAPE CHANGED — possibly breaking

user

- user.name: string
~ user.email: string → number
~ user.profile.avatar: null → string  (was null)
+ user.full_name: string

3 breaking changes
1 non-breaking addition

Options

shapecheck("user", response, {
  snapshotDir: ".shapecheck",       // default ".shapecheck"
  failOnBreakingChange: true,       // sets process.exitCode = 1 for CI
  ignore: ["updated_at", "last_seen"],
});

Breaking (potentially): type changes, removed fields, object ↔ array. Non-breaking: added fields (snapshots auto-update for non-breaking drift so your baseline stays current).

Direct diff, no storage

import { diffShape } from "shapedrift";

diffShape(oldResponse, newResponse);
// { changed: true, breaking: true, changes: [{ kind: "typeChange", path: "user.email", from: "string", to: "number", ... }] }

CLI

List the contracts detected for your project:

npx shapecheck

Supported

• string · number · boolean · null · undefined · bigint · date
• nested objects, nested arrays, uniform arrays (roles: ["string"])
• arrays of objects key-merged across items (users: [{ id, name }])

Zero dependencies. ESM + CJS + .d.ts + bin. Node >= 18.

License

MIT