# aidenybai/react-scan architecture

> Architecture diagram of the GitHub repository aidenybai/react-scan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aidenybai/react-scan
- Repository: https://github.com/aidenybai/react-scan

## Overview

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: [`packages/scan/src/core/index.ts`](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/core/index.ts) (Scan core), [`packages/scan/src/index.ts`](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/index.ts) (Scan entry), [`packages/scan/src/web/views/index.tsx`](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/web/views/index.tsx) (Diagnostics UI), [`packages/extension/src/inject/react-scan.ts`](https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/inject/react-scan.ts) (Injected scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_scan_entry["Scan entry<br/>bundle entry<br/>[index.ts]"]
  node_scan_core["Scan core<br/>instrumentation<br/>[index.ts]"]
  node_scan_notifications[("Event stores<br/>state pipeline")]
  node_scan_outlines(("Outlines<br/>rendering worker<br/>[index.ts]"))
  node_scan_names["Name adapters<br/>build adapters<br/>[index.ts]"]
  node_scan_web["Diagnostics UI<br/>web UI<br/>[index.tsx]"]
  node_scan_monitoring["Monitoring<br/>env hooks<br/>[next.ts]"]
end

subgraph group_delivery["Delivery surfaces"]
  node_ext_bg["Extension bg<br/>extension background<br/>[index.ts]"]
  node_ext_content["Content bridge<br/>extension content<br/>[index.ts]"]
  node_ext_inject["Injected scan<br/>page inject<br/>[react-scan.ts]"]
  node_vite_plugin["Vite plugin<br/>bundler plugin<br/>[index.ts]"]
end

subgraph group_surfaces["Product surfaces"]
  node_website["Website<br/>Next.js site<br/>[page.tsx]"]
  node_kitchen_sink["Kitchen sink<br/>demo app<br/>[main.tsx]"]
  node_e2e_tests["E2E tests<br/>playwright suite<br/>[inspector.spec.ts]"]
end

subgraph group_tooling["Repo tooling"]
  node_release["Release flow<br/>changesets<br/>[config.json]"]
  node_ci["CI builds<br/>github actions"]
end

node_scan_entry -->|"bootstraps"| node_scan_core
node_scan_entry -->|"loads UI"| node_scan_web
node_scan_core -->|"emits events"| node_scan_notifications
node_scan_core -->|"drives overlays"| node_scan_outlines
node_scan_names -->|"enriches"| node_scan_core
node_scan_monitoring -->|"hooks runtime"| node_scan_core
node_scan_notifications -->|"powers views"| node_scan_web
node_scan_outlines -->|"renders overlays"| node_scan_web
node_ext_bg -->|"coordinates"| node_ext_content
node_ext_content -->|"bridges"| node_ext_inject
node_ext_inject -->|"uses core"| node_scan_core
node_ext_inject -->|"shows UI"| node_scan_web
node_vite_plugin -->|"bundles scan"| node_scan_entry
node_website -->|"documents"| node_scan_entry
node_kitchen_sink -->|"demonstrates"| node_scan_entry
node_e2e_tests -->|"verifies"| node_scan_web
node_e2e_tests -->|"verifies"| node_ext_inject
node_release -->|"feeds"| node_ci
node_ci -->|"packages"| node_ext_bg
node_website -->|"publishes"| node_release

click node_scan_entry "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/index.ts"
click node_scan_core "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/core/index.ts"
click node_scan_notifications "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/core/notifications/performance-store.ts"
click node_scan_outlines "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/new-outlines/index.ts"
click node_scan_names "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/react-component-name/index.ts"
click node_scan_web "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/web/views/index.tsx"
click node_scan_monitoring "https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/monitoring/next.ts"
click node_ext_bg "https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/background/index.ts"
click node_ext_content "https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/content/index.ts"
click node_ext_inject "https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/inject/react-scan.ts"
click node_vite_plugin "https://github.com/aidenybai/react-scan/blob/main/packages/vite-plugin-react-scan/src/index.ts"
click node_website "https://github.com/aidenybai/react-scan/blob/main/packages/website/app/page.tsx"
click node_kitchen_sink "https://github.com/aidenybai/react-scan/blob/main/kitchen-sink/src/main.tsx"
click node_e2e_tests "https://github.com/aidenybai/react-scan/blob/main/e2e/inspector.spec.ts"
click node_release "https://github.com/aidenybai/react-scan/blob/main/.changeset/config.json"
click node_ci "https://github.com/aidenybai/react-scan/blob/main/.github/workflows/build-extension.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scan_entry,node_scan_core,node_scan_notifications,node_scan_outlines,node_scan_names,node_scan_web,node_scan_monitoring toneBlue
class node_ext_bg,node_ext_content,node_ext_inject,node_vite_plugin toneAmber
class node_website,node_kitchen_sink,node_e2e_tests toneMint
class node_release,node_ci toneRose
```

## Components

### Core runtime

Shared scanning engine and diagnostics UI in packages/scan

- [Scan entry](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/index.ts): bundle entry · Public bootstrap and CLI entrypoints for the scan package · `packages/scan/src/index.ts`
- [Scan core](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/core/index.ts): instrumentation · React render/commit observation and core runtime behavior · `packages/scan/src/core/index.ts`
- [Event stores](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/core/notifications/performance-store.ts): state pipeline · Performance, interaction, and notification stores that normalize scan events · `packages/scan/src/core/notifications/performance-store.ts`
- [Outlines](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/new-outlines/index.ts): rendering worker · High-performance outline and overlay drawing path · `packages/scan/src/new-outlines/index.ts`
- [Name adapters](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/react-component-name/index.ts): build adapters · Framework and bundler integrations that improve component-name inference · `packages/scan/src/react-component-name/index.ts`
- [Diagnostics UI](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/web/views/index.tsx): web UI · Toolbar, inspector, notifications, widget, and overlay views · `packages/scan/src/web/views/index.tsx`
- [Monitoring](https://github.com/aidenybai/react-scan/blob/main/packages/scan/src/monitoring/next.ts): env hooks · 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](https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/background/index.ts): extension background · Long-lived extension state, icon, and browser chrome coordination · `packages/extension/src/background/index.ts`
- [Content bridge](https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/content/index.ts): extension content · Bridges extension messaging into the page context · `packages/extension/src/content/index.ts`
- [Injected scan](https://github.com/aidenybai/react-scan/blob/main/packages/extension/src/inject/react-scan.ts): page inject · Script injected into inspected pages, including page-side React Scan logic · `packages/extension/src/inject/react-scan.ts`
- [Vite plugin](https://github.com/aidenybai/react-scan/blob/main/packages/vite-plugin-react-scan/src/index.ts): bundler plugin · Thin integration layer for Vite-based apps · `packages/vite-plugin-react-scan/src/index.ts`

### Product surfaces

Website, demos, and validation harnesses

- [Website](https://github.com/aidenybai/react-scan/blob/main/packages/website/app/page.tsx): Next.js site · Public docs, marketing pages, replay demo, and waitlist API · `packages/website/app/page.tsx`
- [Kitchen sink](https://github.com/aidenybai/react-scan/blob/main/kitchen-sink/src/main.tsx): demo app · Standalone Vite demo used to exercise React Scan against real patterns · `kitchen-sink/src/main.tsx`
- [E2E tests](https://github.com/aidenybai/react-scan/blob/main/e2e/inspector.spec.ts): playwright suite · End-to-end checks for inspector, notifications, outlines, and toolbar · `e2e/inspector.spec.ts`

### Repo tooling

Release, build, and test automation

- [Release flow](https://github.com/aidenybai/react-scan/blob/main/.changeset/config.json): changesets · Versioning and package publishing across the monorepo · `.changeset/config.json`
- [CI builds](https://github.com/aidenybai/react-scan/blob/main/.github/workflows/build-extension.yml): github actions · Automated build and packaging workflows, especially for the extension · `.github/workflows/build-extension.yml`

## Connections

- 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
