ContextQMD
Back to Plate

React Scan should stay an opt-in dev microscope, not a benchmark gate

docs/solutions/performance-issues/2026-04-11-react-scan-should-stay-an-opt-in-dev-microscope-not-a-benchmark-gate.md

53.0.62.6 KB
Original Source

React Scan should stay an opt-in dev microscope, not a benchmark gate

Problem

The large-document roadmap still needed more experimentation, but adding another profiler without a clear role was a good way to create fake certainty.

react-scan is useful for showing what React is touching. It is not useful as the thing that decides whether the architecture is right.

Symptoms

  • kept browser lanes already existed for huge-document typing, select-all, and paste
  • kept breadth lanes already showed that sibling-leaf and ancestor breadth were mostly green
  • a visual profiler could easily duplicate existing knowledge while still perturbing the runtime enough to make timing numbers lie

What Didn't Work

  • treating profiler overlays as if they were benchmark artifacts
  • adding a permanent dependency just to support a temporary local experiment
  • wiring a profiler into normal runs instead of making it explicit and opt-in

Solution

Use react-scan only as an opt-in local profiler in the site app.

Kept integration:

  • site/pages/_app.tsx checks for ?reactScan=1
  • when present in development, it injects the official loader: https://unpkg.com/react-scan/dist/auto.global.js
  • without that query param, the app behaves exactly as before

This keeps the tool available for experimentation while leaving the benchmark lanes clean.

Why This Works

The repo already has the real truth sources:

  • huge-document benchmark lanes
  • chunking compare lanes
  • rerender-breadth lane

Those tell us whether a change is worth keeping.

react-scan answers a different question:

  • what is React touching during this local experiment?

That makes it a microscope, not the judge.

Prevention

  • keep visual profilers opt-in
  • never promote profiler overlays to gate truth
  • if profiler output and kept benchmarks disagree, trust the kept benchmarks
  • use react-scan for:
    • huge-document typing investigation
    • shell-promotion experiments
    • broad-op regression diagnosis
  • stop using it once it stops changing design decisions