How aidenybai/react-scan works
This repository is a pnpm monorepo for React Scan, a performance-diagnostics tool for React applications. The architecture splits cleanly into three major product surfaces:
1. the runtime scanning library,
2. delivery/integration surfaces that inject that runtime into apps,
3. the website, demos, and test harnesses used to ship and validate it.
At a high level, the flow is:
application loads React Scan via script tag, bundler plugin, or browser extension → React Scan instruments React render/commit activity → render/performance events are normalized into internal stores → those stores drive overlays, toolbar, inspector, notifications, and other visual diagnostics.
Main subsystems
• packages/scan
- This is the core product package and the largest subsystem.
- It contains:
- runtime instrumentation and core logic in src/core
- component-name inference and framework/bundler adapters in src/react-component-name
- visual diagnostics UI in src/web
- outline rendering and overlay drawing in src/new-outlines
- environment-specific monitoring in src/monitoring
- install/bootstrap entrypoints like src/auto.ts, src/install-hook.ts, src/index.ts, and CLI tooling in src/cli.mts
- This package is both a library and a bundle producer: it ships the scanning logic plus the UI surfaces that render the inspector/toolbar/notifications.
• packages/extension
- Browser-extension wrapper around the same core scanning experience.
- It is split into the standard extension boundaries:
- background/ for long-lived extension state and icon/state management
- content/ for page-context bridging
- inject/ for the script injected into the inspected page
- It has separate manifests for Chrome and Firefox, and packages built zips for each browser.
- The extension is not the scanner itself; it is a distribution and control layer that injects the scanner/UI into pages and surfaces it through browser chrome.
• packages/vite-plugin-react-scan
- A bundler integration package that wires React Scan into Vite-based apps.
- This is a thin adaptation layer around the core package, letting Vite users add React Scan during build/dev without manual script injection.
• packages/website
- The public documentation and marketing site, built with Next.js.
- It includes:
- installation docs and product pages
- an API route for waitlist/signup handling at app/api/waitlist/route.ts
- a replay/demo page
- a public/auto.global.js asset for the no-code bootstrap path
- This package is the primary external-facing information surface, not part of the scanner runtime.
• kitchen-sink
- A standalone Vite demo application with example components and scenarios.
- Used for local development and behavior verification of the scanner against real React patterns.
- It contains example apps like todo list, Sierpinski, and e2e fixture cases.
• e2e
- End-to-end Playwright tests covering the major user-facing surfaces:
- inspector
- notifications
- outlines
- toolbar
- These tests validate the integrated product behavior across the runtime and UI layers.
Core runtime architecture inside packages/scan
The core package is organized around a data pipeline:
• instrumentation layer
- Detects React renders, commits, and relevant component activity.
- This is the low-level observation layer that gathers facts from React and the host environment.
• normalization and state layer
- Data is stored and transformed in feature-specific stores such as performance, interaction, and notification stores.
- The core/notifications area suggests a structured event pipeline for render events, interaction tracking, performance analysis, and overlay coordination.
• visualization layer
- The web/ subtree renders the actual user-facing diagnostics:
- toolbar
- inspector
- notifications panel
- widget
- overlays and timeline views
- Shared hooks/components/utilities support these views.
- The UI reads from central state stores rather than directly from the instrumentation layer, which keeps the observation logic separate from presentation.
• outline rendering subsystem
- src/new-outlines and its worker/offscreen-canvas files indicate a dedicated high-performance rendering path for component outlines/highlights.
- This is an important boundary: the overlay drawing work is offloaded from normal UI rendering, likely to keep the diagnostics lightweight.
• component naming subsystem
- src/react-component-name contains adapters for multiple build environments: Babel, esbuild, Rollup, Vite, Webpack, Rspack, Rolldown, Astro, and TypeScript-based helpers.
- This subsystem enriches runtime diagnostics with human-readable component names.
- Architecturally, it sits at the build-time boundary: it helps the scanner produce better labels without requiring app code changes.
How the product is delivered into apps
React Scan supports multiple entry paths, which is why the repository has several integration layers:
• script tag / global bundle
- The README shows auto.global.js as the simplest path.
- This is the “drop it in” mode for apps that can load a script before their app bundle.
• framework/bundler plugins
- The Vite plugin and the framework-specific docs under docs/installation/ show that React Scan is intended to be integrated into many app setups without rewriting application code.
- The presence of many bundler adapters in react-component-name reinforces this framework-agnostic approach.
• browser extension
- A separate extension distribution injects the same scanning capability into arbitrary sites for inspection without modifying the target app.
Important boundaries
• runtime vs presentation
- The scanning/instrumentation logic is separated from the UI used to inspect it.
- This makes it possible to reuse the same core observation logic across script-tag usage, extension usage, and local demos.
• app context vs extension context
- The extension has a background/content/inject split because it must bridge browser-extension privileges with page execution.
- The injected page code is distinct from the extension UI and state management.
• build-time naming vs runtime scanning
- Component-name extraction is handled by environment-specific compiler plugins/adapters.
- Runtime scanning can work independently, but diagnostics are richer when the build-time path is available.
• high-frequency rendering vs main-thread UI
- Outline drawing uses a worker/offscreen-canvas path, indicating a deliberate boundary for expensive rendering work.
Tooling, runtime, and release infrastructure
• TypeScript is the primary implementation language across the repo.
• Vite is used heavily for local dev/build in the scan package, the extension package, the kitchen-sink demo, and plugin development.
• Next.js powers the website package.
• Tsup appears in the scan package for packaging/build output.
• Playwright drives end-to-end validation.
• Changesets manage versioning/release notes across packages.
• GitHub Actions automate builds and packaging, especially for the browser extension.
• The repo publishes multiple artifacts:
- npm packages
- browser-extension zips
- website assets
- demo build outputs
If you were drawing this architecture, the most important top-level boxes would be:
• React Scan core runtime
• UI/overlay/inspector layer
• integration adapters (script tag, Vite plugin, browser extension)
• framework-specific name-resolution adapters
• demo/website/test surfaces
The central dependency direction is from integrations into the shared scan core, and from the core into the shared diagnostics stores/UI. The website and demos consume the published artifacts; they do not participate in the scanner’s runtime decision-making.
Main entry points: core/index.ts Scan core · src/index.ts Scan entry · index.tsx Diagnostics UI · react-scan.ts Injected scan
Components 16
Core runtime
Shared scanning engine and diagnostics UI in packages/scan
- Scan entry · Public bootstrap and CLI entrypoints for the scan package
packages/scan/src/index.ts - Scan core · React render/commit observation and core runtime behavior
packages/scan/src/core/index.ts - Event stores · Performance, interaction, and notification stores that normalize scan events
packages/scan/src/core/notifications/performance-store.ts - Outlines · High-performance outline and overlay drawing path
packages/scan/src/new-outlines/index.ts - Name adapters · Framework and bundler integrations that improve component-name inference
packages/scan/src/react-component-name/index.ts - Diagnostics UI · Toolbar, inspector, notifications, widget, and overlay views
packages/scan/src/web/views/index.tsx - Monitoring · Environment-specific hooks such as Next.js monitoring integration
packages/scan/src/monitoring/next.ts
Delivery surfaces
Ways React Scan is injected or bundled into apps
- Extension bg · Long-lived extension state, icon, and browser chrome coordination
packages/extension/src/background/index.ts - Content bridge · Bridges extension messaging into the page context
packages/extension/src/content/index.ts - Injected scan · Script injected into inspected pages, including page-side React Scan logic
packages/extension/src/inject/react-scan.ts - Vite plugin · Thin integration layer for Vite-based apps
packages/vite-plugin-react-scan/src/index.ts
Product surfaces
Website, demos, and validation harnesses
- Website · Public docs, marketing pages, replay demo, and waitlist API
packages/website/app/page.tsx - Kitchen sink · Standalone Vite demo used to exercise React Scan against real patterns
kitchen-sink/src/main.tsx - E2E tests · End-to-end checks for inspector, notifications, outlines, and toolbar
e2e/inspector.spec.ts
Repo tooling
Release, build, and test automation
- Release flow · Versioning and package publishing across the monorepo
.changeset/config.json - CI builds · Automated build and packaging workflows, especially for the extension
.github/workflows/build-extension.yml
Connections 20
- Scan entry → Scan core: bootstraps · Public entrypoints initialize the core runtime
- Scan entry → Diagnostics UI: loads UI · The runtime exposes the diagnostics interface
- Scan core → Event stores: emits events · Instrumentation feeds normalized stores
- Scan core → Outlines: drives overlays · Runtime events request outline/highlight rendering
- Name adapters → Scan core: enriches · Build-time adapters improve runtime labels and diagnostics
- Monitoring → Scan core: hooks runtime · Environment-specific monitoring augments core behavior
- Event stores → Diagnostics UI: powers views · Stores feed inspector, notifications, toolbar, and widget UI
- Outlines → Diagnostics UI: renders overlays · Offscreen drawing path supplies visible highlights
- Extension bg → Content bridge: coordinates · Background state and messaging flow to content scripts
- Content bridge → Injected scan: bridges · Content scripts hand off execution into the page context
- Injected scan → Scan core: uses core · Injected page code loads the shared scanning runtime
- Injected scan → Diagnostics UI: shows UI · Injected runtime activates diagnostics surfaces in the page
- Vite plugin → Scan entry: bundles scan · The plugin wires the scan package into Vite apps
- Website → Scan entry: documents · Site explains installation and no-code bootstrap paths
- Kitchen sink → Scan entry: demonstrates · Demo app exercises the runtime in realistic component patterns
- E2E tests → Diagnostics UI: verifies · Playwright covers the user-facing diagnostics surfaces
- E2E tests → Injected scan: verifies · Tests cover the extension-injected experience as an integrated path
- Release flow → CI builds: feeds · Versioning and release artifacts are built in CI
- CI builds → Extension bg: packages · Workflows produce browser-extension artifacts
- Website → Release flow: publishes · Site and package releases are coordinated through repo versioning