aidenybai/react-scan

Scan for React performance issues and eliminate slow renders in your app

Summary

React Scan is a TypeScript tool that automatically detects performance issues in React applications. It runs without code changes by adding a script tag, and it visually highlights components that re-render so engineers can spot wasted work quickly.

What it is useful for

React Scan is useful for diagnosing unnecessary re-renders that hurt performance. The README explains that React compares component props by reference, so passing new inline objects or functions on every render (for example, onClick={() => alert("hi")} or style={{ color: "purple" }}) can trigger renders even when the output is identical. The tool surfaces these situations by highlighting renders on screen and offering an always-accessible toolbar overlay. It is also useful for verifying that memoization (React.memo, useMemo, useCallback) is actually working, debugging render storms, and confirming the impact of a refactor before shipping. A documented limitation is that forcing it to run in production is described as "not recommended" in the README, so it is primarily a development-time diagnostic.

How engineers can use it

The fastest path documented in the README is the initializer, which detects your framework and sets things up:

npx -y react-scan@latest init

For manual setup, the README shows installing as a dev dependency and adding the auto-loader script before any other scripts. Concrete examples from the README:

• Plain HTML: paste the unpkg script tag (//unpkg.com/react-scan/dist/auto.global.js) before your app scripts in index.html.
• Next.js (App Router): load it via next/script with strategy="beforeInteractive" inside app/layout.tsx.
• Next.js (Pages Router): load it inside pages/_document.tsx.
• Vite: add the script tag to the <head> of index.html before /src/main.tsx.
• Remix: add it inside the <head> of app/root.tsx.

For programmatic control, the API exposes scan(options), the useScan(options) hook, setOptions, getOptions, and onRender(Component, fn) to inspect a specific component's render history. The Options type supports toggling the toolbar, console logging via log: true, adjusting animationSpeed, and lifecycle callbacks (onCommitStart, onRender, onCommitFinish). A browser extension is also documented in the repository's BROWSER_EXTENSION_GUIDE.md.