react-scan README

The project's README from github.com/aidenybai/react-scan. As one markdown file: README.md.

React Scan

You can still use React Scan, but we recommend React Doctor

React Doctor brings React Scan’s performance focus to coding agents, with static checks for architecture, security, accessibility, and more. Try React Doctor →

React Scan automatically detects performance issues in your React app.

Quick Start

npx -y react-scan@latest init

Try out a demo! →

React Scan in action

Install

The init command will automatically detect your framework, install react-scan via npm, and set up your project.

npx -y react-scan@latest init

Manual Installation

Install the package:

npm install -D react-scan

Then add the script tag to your app. Pick the guide for your framework:

Script Tag

Paste this before any scripts in your index.html:

<!-- paste this BEFORE any scripts -->
<script
  crossOrigin="anonymous"
  src="//unpkg.com/react-scan/dist/auto.global.js"
></script>

Next.js (App Router)

Add this inside of your app/layout.tsx:

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="//unpkg.com/react-scan/dist/auto.global.js"
          crossOrigin="anonymous"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Next.js (Pages Router)

Add this into your pages/_document.tsx:

import { Html, Head, Main, NextScript } from "next/document";
import Script from "next/script";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <Script
          src="//unpkg.com/react-scan/dist/auto.global.js"
          crossOrigin="anonymous"
          strategy="beforeInteractive"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Vite

Example index.html with React Scan enabled:

<!doctype html>
<html lang="en">
  <head>
    <script
      crossOrigin="anonymous"
      src="//unpkg.com/react-scan/dist/auto.global.js"
    ></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Remix

Add this inside your app/root.tsx:

import { Links, Meta, Outlet, Scripts } from "@remix-run/react";

export default function App() {
  return (
    <html>
      <head>
        <Meta />
        <script
          crossOrigin="anonymous"
          src="//unpkg.com/react-scan/dist/auto.global.js"
        />
        <Links />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  );
}

Browser Extension

Install the extension by following the guide here.

API Reference

Options 
export interface Options {
  /**
   * Enable/disable scanning
   * @default true
   */
  enabled?: boolean;

  /**
   * Force React Scan to run in production (not recommended)
   * @default false
   */
  dangerouslyForceRunInProduction?: boolean;

  /**
   * Log renders to the console
   * @default false
   */
  log?: boolean;

  /**
   * Show toolbar bar
   * @default true
   */
  showToolbar?: boolean;

  /**
   * Animation speed
   * @default "fast"
   */
  animationSpeed?: "slow" | "fast" | "off";

  onCommitStart?: () => void;
  onRender?: (fiber: Fiber, renders: Array<Render>) => void;
  onCommitFinish?: () => void;
}

Why React Scan?

React can be tricky to optimize.

The issue is that component props are compared by reference, not value. This is intentional -- rendering can be cheap to run.

However, this makes it easy to accidentally cause unnecessary renders, making the app slow. Even production apps with hundreds of engineers can't fully optimize their apps (see GitHub, Twitter, and Instagram).

<ExpensiveComponent onClick={() => alert("hi")} style={{ color: "purple" }} />

React Scan helps you identify these issues by automatically detecting and highlighting renders that cause performance issues.

Resources & Contributing

Want to try it out? Check the demo.

Looking to contribute? Check the Contributing Guide.

Want to talk to the community? Join our Discord.

Find a bug? Head to our issue tracker.

→ Start contributing on GitHub

Acknowledgments

License

React Scan is MIT-licensed open-source software by Aiden Bai, Million Software, Inc., and contributors.

react-scan (aidenybai/react-scan)

Searching Database…

21.9K ·GitHub
React-scan
What is this?React Scan is a dev tool that automatically detects performance issues in your React app: it highlights exactly the components you need to optimize, requires no code changes, and stays accessible through a toolbar on the page.
Is it something I install into my project, or a separate app?Both: it ships as an npm package you drop into your app via a script tag, and as a standalone browser extension if you would rather not touch your code.
What is the quickest way to add it to my app?Run the init command in your project: it auto-detects your framework, installs react-scan via npm, and wires everything up. The manual route is installing the package and adding its script tag yourself.
Does it work with frameworks like Next.js?Yes — there are copy-paste guides for Next.js (App Router), Remix, and a plain script tag for any index.html; the init command also detects your framework on its own.
Should I still pick it up, or has something replaced it?It still works and remains open source, but the README now points users to React Doctor, which brings the performance focus to coding agents and adds static checks for architecture, security and accessibility.
Is it free to use in my own projects?Yes — React Scan is MIT-licensed open-source software by Aiden Bai, Million Software, Inc. and contributors.
What actually makes React apps slow, in its view?Component props are compared by reference, not value, so it is easy to trigger renders that are not needed — React Scan highlights exactly those. Even production apps with hundreds of engineers (GitHub, Twitter, Instagram are cited) cannot fully optimize theirs.
Can I hook into renders from my own code?Yes — the API includes scan() and the useScan() hook to start scanning, setOptions()/getOptions() for runtime control, and onRender() to run a callback on a specific component's renders.
What inspired it?React Devtools for the initial idea of highlighting renders, Million Lint for scanning and linting approaches, and Why Did You Render? for the concept of detecting unnecessary renders.
Can I try it without installing anything?Yes — the README links an online demo where you can see the render highlighting in action before adding it to your app.
What are similar projects?million, vConsole, redux-devtools-extension, devtools-v6, redux-devtools, web-source-inspect, zustand, react-grab
Which topics is it in?profiler, devtools, optimization, debugging, rendering, browser-extension, nextjs, web-development, performance, react, npm, frontend
Creator
aidenybai
Size
43.9 MB
Stars
21.9K
Updated
CommitAug 16Releasev0.4.3Jun 29
Age
2y
Commits · 90 Days