flawless-react

Docs

Start here — what flawless-react does, how to install it, and where the rest of these pages lead.

What it is

flawless-react is a multi-task quality kit for React components. Point it at a .tsx file (or a glob such as src/**/*.tsx), pick which of the seven tasks to run, and it reads each component’s type signature, walks its JSX to discover locally-imported children, and produces a runnable Playwright + Vitest suite, an accessibility scan, and a Biome-driven correctness report — with file:line findings for every issue. Run it with no arguments for an interactive checkbox menu. The generated suite is a standalone project that knows nothing about the tool once written. A re-run regenerates derived files so they track your source, while the files meant to hold your work — budgets, host wrapper, provider fixtures, MSW handlers, colocated specs — are kept: tighten budgets, add scenarios and swap in real fixtures like any other test code.

curl -fsSL https://raw.githubusercontent.com/lariocpt/flawless-react/main/install.sh | bash

That is the standalone binary — no Bun needed on the target machine. The source package (bun add -g @lariocpt/flawless-react) needs Bun >= 1.1 but carries @biomejs/biome as a real dependency, so every task works with no further setup. The difference matters for two of the seven tasks; see Install.

Where to next

  • Intro — why the tool exists and what the hours of hand-written harness boilerplate look like without it.
  • Install — the two channels, what each one ships, and the biome caveat for the binary.
  • Quickstart — generate a suite for one component and get a green Playwright run.
  • Recipes — task-shaped walkthroughs: first suite, Next.js adoption, mocks with real shapes, crust load pipes, CI wiring, safe regeneration.
  • CLI reference — every flag, its default, and its effect.
  • What gets generated — the emitted suite file by file, and what to change in each.
  • Next.js mode — --nextjs router detection, MSW handlers from your API routes, and output under <project-root>/flawless/.
  • Extending a suite — patterns for editing generated specs without regretting it.
  • Case study: a whole app — all seven tasks over 181 components of a real Next.js app, and what the tool refused to guess.
  • Architecture — the analyse phase, the scaffold phase, and why they are split.
  • Limits & troubleshooting — what the static analyser deliberately does not do, and fixes for the common failure messages.
  • Agent skills — the seven Claude Code skills the tool ships, and what each stops an agent getting wrong.

At a glance

The seven task ids, and what each one leaves behind:

Task idWhat it produces
perf-harnessA Playwright suite driven by React’s built-in <Profiler> and react-scan — a bundled host page, one spec per analysed component, per-component budgets.json, and .heapsnapshot files under heaps/.
unit-browserVitest + @testing-library/react unit tests plus Playwright functional browser specs for every component in the tree.
perf-staticreports/<Component>.perf-static.json — rerender and memoisation risks (children rendered with no useMemo/useCallback/memo/useRef) and props the analyser could not synthesise a default for.
a11yreports/a11y.json (one aggregate per run) — Biome’s accessibility rules over the targeted tree, as file:line findings.
react-rulesreports/react-rules.json (one aggregate per run) — a curated set of bug-catching React and hooks rules via Biome (useExhaustiveDependencies, useHookAtTopLevel, useJsxKeyInIterable, and friends), bypassing any local biome.json.
e2ee2e/<route>.spec.ts — one Playwright spec per app-router page: the route loads with no console or page errors, plus interactions harvested from its component tree. Needs --nextjs or --expo.
loadload/routes.pipes — crust load pipes per route and per API operation. Each run writes load/last-<name>.json; you promote one to load/baseline-<name>.json by hand, and later runs then fail when p95 exceeds 2x it.

Findings also surface where the code lives: a small <Component>.flawless.json is dropped next to each source file unless you pass --no-inline-summary.

perf-harness, unit-browser, perf-static, e2e and load run anywhere. a11y and react-rules shell out to biome, which the binary cannot carry inside itself — it looks for biome in the project being scanned (node_modules/.bin/biome) and then on PATH.