Crispy Profiling

🥓 crispy-profiling

Snapshot testing for React re-renders — deterministic, runtime-proven, with the fix.

crispy-profiling is a React re-render profiler (npm: crispy-profiling): CLI, GitHub Action, MCP server and Agent Skill. Not related to the crispy style-guide package or to the scientific software of the same name.

Your React app feels slow when you type or click? crispy shows which components re-render for no reason, and the exact line to fix.

Quick start

npm i -D crispy-profiling   # or: pnpm add -D crispy-profiling · yarn add -D crispy-profiling

npx crispy install # downloads Chromium once (if that fails, an installed Chrome/Chromium is used) npx crispy scan # zero config: starts your dev server, finds interactions, profiles them npx crispy test # records crispy.snap.json from the scanned scenarios → commit it

Using pnpm or yarn? Run the same commands as pnpm exec crispy … or yarn crispy ….

New to this? Three things to know.

1. crispy scan only *looks* at your app: it edits none of your code and sends nothing anywhere (requests that would change data are blocked).
2. It prints a short list of root causes. Each names a file and a line and says what to change. "No avoidable renders" means the flows it tried are fine; its Not tried lines say what it skipped, and crispy.config.json is where you add the interaction that feels slow.
3. After a fix, run npx crispy test again: 🟢 means fewer renders (check that the screen still updates), 🔴 means a render came back. Nothing is saved over your snapshot unless you ask (-u).

Words you will see: a render is React running a component again; avoidable means its inputs did not really change, so the screen would look the same without it; hoist means move a constant out of the component; memoize means keep the same value or function between renders (useMemo, useCallback, React.memo). A component re-renders whenever its parent does, even with the same props, unless it is wrapped in React.memo; and React.memo only skips the render when its props are stable, so crispy usually asks for both.

crispy scan detects Next.js/Vite, the dev URL (the port your dev server prints, e.g. server.port in vite.config.ts) and your dev command, visits a few routes, tries their safe interactions (buttons, including icon-only ones, tabs, selects, text inputs, internal links, rows of a table or list with a pointer cursor — never anything named delete, pay, sign out, submit…, in several languages), and prints the top root causes with the fix. Like every crispy command, it is read-only: requests other than GET and messages the page sends over a WebSocket never leave the browser (hot-reload sockets excepted), and an interaction that tried to send one is reported and not saved (--allow-writes for apps with disposable data). Point it at a development or preview build, not production. It saves what it ran as crispy.config.json, so crispy test guards those flows from then on. It adds .crispy/ (reports) to .gitignore; commit crispy.config.json and crispy.snap.json. On shadcn-admin it found the first root causes in 2.5 minutes without a single line of config. Prefer writing the steps yourself? npx crispy init creates a config to edit.

From then on, npx crispy test (locally, in CI or from an AI agent) fails when a component starts re-rendering, and tells you why and how to fix it:

| 🔴 regressed | list / interaction | Row | renders | — → 20 | recreated on every render (rendered at

src/App.tsx:222 (App)): onSelect is a new function with the same code in App: wrap it in useCallback with the values it uses as dependencies. Then wrap this component in React.memo. |

For a one-off look at a flow, npx crispy run prints every component with its causes and a fix:

| Component | Renders | Avoidable | Callback | Why it rendered         | Rendered at             | Why / how to fix |

| Row | 20 | 0 | 20 | recreated callbacks 20 | src/App.tsx:222 (App) | onSelect is a new function with the same code in App: wrap it in useCallback… | | Status | 1 | 1 | 0 | recreated props 1 | src/App.tsx:178 (App) | style is recreated with equal data in App: hoist it out of the component or wrap it in useMemo… | | App | 1 | 0 | 0 | own state 1 | src/main.tsx:12 | state updates here cause 23 avoidable render(s) below (Row, Header, Status)… |

Every phase starts with Root causes — fix these first: the few components that recreate a value, recreate a context value or update state that re-renders unchanged children, ranked by the avoidable renders they cause, with the child where one React.memo would stop most of a cascade.

_"Rendered at" and definedIn are mapped back to your original source files and lines through the source maps your dev server or bundler serves (Vite, webpack, Turbopack); without source maps they refer to the code the browser runs._

Works with Vite and Next.js (Turbopack and webpack dev servers); framework internals such as the Next.js dev overlay are filtered out. Profile the development build.

Status: early (0.x), improving every week. Validated on five open-source apps (Redux

Essentials, Next.js App Router Playground, Excalidraw, shadcn-admin, react-admin): it found a

fixable re-render problem in each. See Known limitations and the

changelog. Bug reports, wrong hints and case studies are the most valuable

contribution right now.

crispy-profiling opens your React app in headless Chromium, runs the interactions you describe, and tells you which components rendered, how many times, why (props / state / context / parent) and which renders were avoidable. Per-component render counts are reproducible, so two reports of the same scenario only differ when the code changed (commit counts and effect cascades can vary with load timing; snapshots store them as ranges). That makes it a reliable feedback loop for:

• AI coding agents: an MCP server and an Agent Skill so Claude Code, Cursor, Codex, Copilot & co. can *measure* a re-render fix instead of guessing.
• CI: render budgets and baseline comparison that fail a PR when a component starts re-rendering.
• You: a CLI that answers "why does this re-render?" without opening DevTools.

No code changes in your app: it uses the same hook React DevTools uses. Tested on React 19 and validated on 18.3 and 19.0 apps; React 16.8–17 expose the same hook but are not tested.

Render snapshots (crispy test)

Like Jest snapshots, but for re-renders. Commit the expected render counts of your key flows; every PR — written by a person or an AI agent — is checked against them at runtime.

npx crispy test        # 1st run: writes crispy.snap.json → commit it

npx crispy test # later: fails if any component renders more (or more avoidably) npx crispy test -u # accept intended changes / lock in improvements npx crispy test --ci # in CI: a missing snapshot fails instead of being written (auto-detected; --no-ci to opt out)

When something regresses you get the component, the cause, where it is rendered and the fix (see Quick start).

crispy.snap.json has one line per component, so the PR diff shows exactly which counts changed:

"interaction": {

"commits": 1, "components": { "App": { "renders": 1, "avoidable": 0 }, "Header": { "renders": 1, "avoidable": 1 } } }

Rules: any increase in renders or avoidable renders fails (snapshot.tolerance allows slack), and every metric is checked independently, so an improvement never hides a regression. More commits are reported as ℹ️ but do not fail, because they vary with load timing (snapshot.failOnMoreCommits to fail). Counts that varied between runs are stored as [min, max] ranges and only fail outside them (-u keeps the known range instead of narrowing it). Decreases pass and suggest -u. New UI passes and is reported (record it with -u); if it already renders avoidably it is flagged ⚠️ (set snapshot.failOnNewAvoidable to fail instead). When the number of renders stays the same but more of them become avoidable — typical right after a fix uncovers the next cause — the row shows 🟡 now avoidable with the fix and does not fail (snapshot.failOnMoreAvoidable to fail). A known component that starts re-rendering in a phase still fails. A rename, even combined with a move to another file, with the same counts is reported as 🔁 renamed, not as a regression. crispy test never edits the committed file on its own; the snapshot always covers every component (even with topComponents); budgets still apply.

In your Playwright tests

Already have Playwright e2e tests? Guard re-renders inside them, no separate scenarios:

import { test } from '@playwright/test';

import { renders } from 'crispy-profiling/playwright';

test('search does not re-render the product list', async ({ page }) => { const r = await renders(page); // before page.goto await page.goto('/'); await r.phase('search'); await page.fill('#search', 'shoes'); await r.toMatchSnapshot('search'); // renders/search.snap.json; fails with cause + fix });

The first run writes the snapshot (commit it); CRISPY_UPDATE=1 accepts intended changes; on CI (CI set) a missing snapshot fails. r.report() returns the full report for custom assertions.

Configuration

crispy.config.json (JSON Schema):

{

"$schema": "./node_modules/crispy-profiling/schema/crispy.config.schema.json", "baseUrl": "http://localhost:5173", "runs": 3, "scenarios": [ { "name": "search", "path": "/products", "steps": [ { "action": "type", "selector": "#search", "value": "shoes" }, { "action": "phase", "name": "sort" }, { "action": "click", "selector": "text=Price: low to high" } ], "budgets": { "interaction": { "maxAvoidableRenders": 0, "components": { "ProductCard": { "maxRenders": 20 } } } } } ] }

| readOnly | true | Block every request other than GE