Onboarding: aidenybai/react-scan

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/aidenybai/react-scan shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 4d ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 55% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live aidenybai/react-scan repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/aidenybai/react-scan.

What it runs against: a local clone of aidenybai/react-scan — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in aidenybai/react-scan | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>aidenybai/react-scan</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of aidenybai/react-scan. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/aidenybai/react-scan.git
#   cd react-scan
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of aidenybai/react-scan and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "aidenybai/react-scan(\\.git)?\\b" \\
  && ok "origin remote is aidenybai/react-scan" \\
  || miss "origin remote is not aidenybai/react-scan (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/aidenybai/react-scan"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

React Scan is a zero-setup performance profiler that automatically detects and visualizes React rendering inefficiencies—unnecessary re-renders, slow components, and render cascades—by injecting a global script that highlights problematic components directly in your app without requiring code changes. It provides a browser-accessible toolbar and optional browser extension to identify exactly which components need optimization. Monorepo structure: root contains core packages (built TypeScript, ~850KB), kitchen-sink/ is a Vite+React demo app for testing, docs/installation/ holds framework-specific guides, e2e/ contains Playwright specs, and .changeset/ tracks version changes. The library is distributed as auto.global.js (global script) and likely npm modules for framework integrations.

Who it's for

React developers (especially at scale—it lists Shopify, Airbnb, Faire, Instagram as users) who need to identify and fix slow renders in production or development without learning complex DevTools workflows or modifying application code.

Maturity & risk

Actively developed and production-ready: the project has major company adoption (Shopify, Airbnb, Instagram), comprehensive framework guides (Next.js, Remix, Vite, Astro, etc.), e2e test coverage (inspector.spec.ts, notifications.spec.ts, toolbar.spec.ts), and GitHub Actions CI/CD. Recent activity is visible through the changeset and build workflows.

Low risk for adoption: single-maintainer (aidenybai) creates maintenance concerns, but the library is pure JavaScript with minimal dependencies (React/React-DOM peer deps only based on kitchen-sink). The global script injection model means it runs in isolation and failures are typically graceful. Breaking changes are managed via .changeset/config.json, suggesting semantic versioning discipline.

Active areas of work

Active development on framework compatibility, e2e testing, and browser extension functionality (build-extension.yml present). The kitchen-sink app uses React 19.2.5 and Vite 6.3.0, indicating recent dependency updates. Changeset config suggests ongoing releases.

Get running

git clone https://github.com/aidenybai/react-scan && cd react-scan && npm install && npm run dev (from kitchen-sink/) to run the demo app locally.

Daily commands: cd kitchen-sink && npm run dev (starts Vite dev server on typical 5173 port). For production build: npm run build. For extension: npm run build-extension.yml (via GitHub Actions).

Map of the codebase

• kitchen-sink/package.json: Demonstrates the exact React 19 + Vite setup where react-scan is consumed; start here to understand how the library integrates
• e2e/inspector.spec.ts: End-to-end tests showing expected behavior of the inspector toolbar, component detection, and UI interactions
• docs/installation/next-js-app-router.md: Concrete example of how the global script integrates into a real framework; pattern is similar for other frameworks
• .github/workflows/build-extension.yml: Defines browser extension build and release pipeline; essential for understanding distribution channels
• .changeset/config.json: Configures semantic versioning and automated releases; critical for understanding versioning discipline and contribution workflow

How to make changes

For core library changes: src/ likely contains the injection logic and component detection (not visible in file list but inferred from auto.global.js dist). For framework docs: add to docs/installation/{framework}.md. For tests: add specs to e2e/ using Playwright. For kitchen-sink examples: modify kitchen-sink/src/examples/.

Traps & gotchas

The library uses global script injection (auto.global.js) which relies on the browser's unpkg CDN; if unpkg is down or blocked, the init command fails. The kitchen-sink demo requires Node 16+ (implied by Vite 6.3.0 and TypeScript 6.0.3 constraints). Framework integrations are opinionated—check docs/installation/ for your exact framework version before installing, as Next.js App Router differs significantly from Pages Router. Browser extension requires manual build via GitHub Actions; it's not pre-built in the repo.

Concepts to learn

• React Render Profiling — React Scan's core capability is identifying which components re-render unnecessarily; understanding React.memo, useMemo, and render bailout mechanisms is essential to act on the data it provides
• Component Fiber Tree Traversal — The library must walk React's internal fiber tree to detect renders; knowledge of how React organizes component instances is necessary for understanding the profiler's detection mechanism
• Global Script Injection & Timing — react-scan injects auto.global.js before your app loads; understanding when it executes relative to React initialization is critical for why it requires 'beforeInteractive' strategy in Next.js
• Source Map Integration — The inspector highlights components by component name; source maps must be present and accessible for accurate attribution, especially in production builds
• Browser Extension Content Scripts — The optional browser extension runs as a content script injecting react-scan into tabs; understanding CSP violations, message passing, and manifest.json is necessary for extension development
• Semantic Versioning via Changesets — The repo uses changesets for versioning discipline; contributors must understand how to document breaking vs. minor changes to maintain semver compliance
• React DevTools Protocol Integration — The profiler likely hooks into or mimics React DevTools' ability to intercept render events; familiarity with how React exposes performance data to external tools is helpful

Related repos

• facebook/react — Core dependency and the framework whose performance this tool optimizes; understanding React's commit phases and batching is essential
• vercel/next.js — Primary framework integration target (Next.js App/Pages Router guides are most detailed); likely high user overlap
• remix-run/remix — Secondary framework integration with dedicated setup guide; important user segment
• preactjs/preact — Lightweight React alternative; react-scan could theoretically extend to Preact but is not currently listed as supported
• million-js/million — Same maintainer ecosystem (react-scan.million.dev in README); sister project for React performance optimization via compilation

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E tests for kitchen-sink examples (Sierpinski & Todo List)

The repo has e2e tests for core features (inspector, notifications, outlines, toolbar) but the kitchen-sink examples (sierpinski and todo-list) lack dedicated E2E test coverage. These are critical for validating that react-scan correctly detects performance issues in realistic component scenarios. Adding tests here ensures the scanner works correctly on complex, nested components.

• [ ] Create e2e/sierpinski.spec.ts to test render detection on the recursive Sierpinski triangle component in kitchen-sink/src/examples/sierpinski
• [ ] Create e2e/todo-list.spec.ts to test list rendering and state update detection in kitchen-sink/src/examples/todo-list
• [ ] Verify that slow renders are correctly highlighted and metrics are accurate for each example
• [ ] Run tests in the build-extension.yml workflow to ensure examples don't regress

Add installation guide for Solid.js and Vue.js (or document framework limitations)

The docs/installation directory contains guides for 8 frameworks (Next.js, Remix, Astro, Vite, etc.), but the README and CONTRIBUTING.md don't clarify which frameworks react-scan supports. Since this is a React-specific tool, new contributors may waste time attempting to add support for non-React frameworks. Either add explicit docs for unsupported frameworks with rationale, or add a SUPPORTED_FRAMEWORKS.md file.

• [ ] Create docs/installation/framework-support.md documenting which frameworks are supported and why (React-only limitation)
• [ ] Update README.md to add a 'Framework Support' section linking to the support matrix
• [ ] Add a note in CONTRIBUTING.md about framework scope to set contributor expectations

Add performance regression tests for react-scan bundle size and initialization overhead

With react-scan being injected into production apps (via CDN and npm), there's no automated check for bundle size bloat or initialization performance. The extension has a build workflow (.github/workflows/build-extension.yml), but there's no corresponding performance budget enforcement. This prevents accidental regressions when optimizing the core scanner.

• [ ] Create a .github/workflows/bundle-size.yml GitHub Action that runs npm run build and measures the compiled package size
• [ ] Add a performance threshold check (e.g., fail if core bundle grows >X KB) and report it on PRs
• [ ] Document the bundle size limits in CONTRIBUTING.md so contributors understand the constraints
• [ ] Optionally add a script in package.json (e.g., npm run size) that developers can run locally

Good first issues

• Add missing installation guide for SvelteKit (pattern exists for Vite, Remix, Next.js; copy and adapt kitchen-sink to Svelte) in docs/installation/sveltekit.md
• Expand e2e/toolbar.spec.ts to test toolbar keyboard shortcuts and dark mode toggle (currently only tests visibility based on toolbar.spec.ts filename)
• Create a TROUBLESHOOTING.md guide documenting common issues like 'React Scan not detecting renders in Suspense boundaries' and 'inspector blank in production builds with sourcemaps disabled'

Top contributors

• @RobPruzan — 55 commits
• @aidenybai — 37 commits
• @github-actions[bot] — 4 commits
• @torytang025 — 2 commits
• @flamrdevs — 1 commits

Recent commits

• ec7b00f — fix (aidenybai)
• ff195e2 — fix (aidenybai)
• 476a4fd — 0.5.6 (aidenybai)
• 0b024de — fix (aidenybai)
• 8da57f9 — feat(scan): copy selected element via react-grab (#438) (aidenybai)
• b8d3509 — 0.5.5 (aidenybai)
• cd7dcfc — fix(scan): triage sweep across open issues (#437) (aidenybai)
• f34a13b — chore: modernize toolchain to vite-plus + turbo and prune dead code (#436) (aidenybai)
• d97d030 — 0.5.4 (aidenybai)
• 17fd4cb — feat(scan): add react-scan/lite headless instrumentation entry (#435) (aidenybai)

Security observations

The react-scan codebase demonstrates generally good security practices with no critical vulnerabilities detected in the dependency configuration. The main concerns are a potentially incorrect TypeScript version specification, missing lockfile visibility, lack of a security disclosure policy, and build artifacts in version control. The project appears to be a legitimate React performance monitoring tool with appropriate private package configurations. Recommendations focus on dependency version verification, proper CI/CD practices, and establishing security communication channels.

• Medium · Outdated TypeScript Version — kitchen-sink/package.json. TypeScript version 6.0.3 specified in devDependencies is a major version that may have breaking changes and compatibility issues. This is unusually high and may indicate a typo or experimental version. Fix: Verify the correct TypeScript version. Typically, use LTS versions like ^5.x or ^4.9.x. Update to a stable, widely-tested version.
• Low · Missing npm Lockfile Verification — package.json, kitchen-sink/package.json. No package-lock.json or yarn.lock file is visible in the file structure. This could lead to non-deterministic installations and potential supply chain attacks if dependencies are modified upstream. Fix: Ensure lockfiles (package-lock.json or yarn.lock) are committed to version control and verified in CI/CD pipelines.
• Low · Development Dependencies in Production — kitchen-sink/package.json. The kitchen-sink package includes devDependencies like Vite and TypeScript that are marked as private but may inadvertently be bundled or exposed. Fix: Ensure proper build configuration separates development and production dependencies. Verify that devDependencies are excluded from production builds.
• Low · Missing SECURITY.md File — Repository root. No security disclosure policy or security.md file is present in the repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting responsible disclosure procedures and security contact information.
• Low · Extension Build Artifacts in Repository — packages/extension/build/. Pre-built extension files (.zip) are committed to version control in packages/extension/build/. These should be generated during CI/CD, not stored in the repository. Fix: Move build artifacts to .gitignore and generate them during the build pipeline instead. Store releases on GitHub Releases or a distribution server.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.