Skip to content
Get packs

Guide · Open source

How to use react-scan: find unnecessary React re-renders

Updated · written with AI from the project's own documentation and checked against our catalogue data

React Scan is an open-source developer tool for React that watches your app while it runs and highlights components that re-render unnecessarily. It is added with a script tag or an npm install and needs no changes to your application code. This guide shows you how to install it, wire it into Next.js, Vite or Remix, and read what it shows you.

React Scanaidenybai/react-scan · ★ 21.9k · MIT

Quick start

  1. 1Check Node.js is installed. React Scan's prerequisite is Node.js. The README does not state a minimum version, so use a current Node.js install.
  2. 2Run the init command. From your project root, run npx -y react-scan@latest init. It detects your framework and sets up the project.
  3. 3Or install manually. Run npm install -D react-scan if you want to configure the script yourself.
  4. 4Add the script for your framework. Place the auto.global.js script tag where the README shows for your setup, before any other scripts.
  5. 5Run your app in development. Start your dev server and open the page. React Scan highlights components that re-render.
  6. 6Inspect highlighted components. Find components that re-render when they should not, and check props passed as new functions or objects.

What react-scan does and when to use it

React Scan automatically detects performance issues in your React app. According to its README, it requires no code changes, highlights the components you need to optimize, and stays accessible through a toolbar on the page.

It is aimed at developers debugging slow React pages in development, and at teams who want to find unnecessary re-renders without reading every component.

  • Good fit: debugging slow pages in development, or getting a visual overlay instead of manual profiling.
  • Not a fit: production monitoring. The README says forcing it to run in production is 'not recommended'.
  • Not a fit: automatic code fixing. The description says 'scan and fix', but the README only describes detecting and highlighting issues.
  • Not a fit: non-React projects, since it targets React specifically.

Install react-scan with the init command

The fastest route is the init command, which the README says will detect your framework, install react-scan via npm, and set up your project. Run it from your project root. Node.js is a prerequisite; the README does not state a required version.

npx -y react-scan@latest init

Install react-scan manually with npm

If you prefer to set things up yourself, install the package as a dev dependency, then add the script tag for your framework as shown in the sections below.

npm install -D react-scan

Add the script to your framework

The README gives a script tag for plain HTML, and examples for Next.js (App Router and Pages Router), Vite and Remix. The script must go before any other scripts. For Next.js App Router, add it in app/layout.tsx with strategy set to beforeInteractive. For Vite, add it to the head of index.html. For Remix, add it inside app/root.tsx.

  • Script tag: paste it in index.html before any scripts.
  • Next.js App Router: app/layout.tsx.
  • Next.js Pages Router: pages/_document.tsx.
  • Vite: index.html.
  • Remix: app/root.tsx.
  • Browser extension: the README links a separate guide in BROWSER_EXTENSION_GUIDE.md.
<script crossOrigin="anonymous" src="//unpkg.com/react-scan/dist/auto.global.js" ></script>

Read the overlay and find the slow components

Once it runs, React Scan highlights components that re-render. The README explains the underlying issue: component props are compared by reference, not value, so it is easy to pass a new function or object on every render and trigger work you did not intend.

The README's example shows an inline function and an inline style object passed as props, which are new on every render. Use the highlights to find components like this, then decide whether a fix is needed.

  • Look for components that highlight when you expect them to stay still.
  • Check the toolbar on the page for controls.
  • Use the options below to adjust what you see.
<ExpensiveComponent onClick={() => alert("hi")} style={{ color: "purple" }} />

Configure options and the API

The README documents an Options interface. Key settings include enabled (default true), log (default false, logs renders to the console), showToolbar (default true), and animationSpeed ("slow", "fast" or "off", default "fast"). The dangerouslyForceRunInProduction option defaults to false.

The README also lists scan(options) and useScan(options) to start scanning, setOptions(options) and getOptions() to change or read settings at runtime, and onRender to hook into a specific component's renders.

  • enabled: turn scanning on or off.
  • log: print renders to the console.
  • showToolbar: show or hide the toolbar.
  • animationSpeed: "slow", "fast" or "off".
  • useScan(options): hook API to start scanning.
  • onRender(Component, handler): listen to renders of one component.

What people use it for

  • Finding components that re-render on every keystroke in a form.
  • Spotting props like inline callbacks or style objects that cause child re-renders.
  • Getting a visual overview of a slow page without reading every component.
  • Logging renders to the console with the log option while debugging.

Frequently asked questions

How do I install react-scan?

Run npx -y react-scan@latest init in your project root to auto-detect your framework and set it up. For a manual setup, run npm install -D react-scan and add the script tag for your framework.

Does react-scan require code changes?

According to the README, no. It is described as requiring no code changes, and you add it with a script tag or the init command.

Is react-scan free to use?

React Scan is MIT-licensed open-source software, according to its README and license section. Check the LICENSE file in the repository for the full terms.

Can I use react-scan in production?

The README does not recommend it. The option to force it to run in production, dangerouslyForceRunInProduction, is described as 'not recommended', so it is intended for development use.

Does react-scan fix performance issues automatically?

No, the README only describes detecting and highlighting components that re-render unnecessarily. You still need to make the code changes yourself.

What are alternatives to react-scan?

Comparable projects listed for this topic include why-did-you-render, React DevTools, and React Doctor. The README notes that the project now recommends React Doctor, a related tool aimed at coding agents.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use react-scan if you are a developer debugging slow React pages in development and want a visual overlay that shows unnecessary re-renders without code changes. Pick something else if you need production monitoring, automatic code fixes, or support for non-React projects, and consider React Doctor, which the README now recommends.

Install options & downloads