Registry / observability / react-scan

react-scan

JSON →
library0.5.3jsnpmunverified

React Scan is a performance monitoring tool for React applications designed to automatically detect re-render issues and potential performance bottlenecks. Unlike React's built-in `Profiler` or other tools like `Why Did You Render?`, `react-scan` aims to provide simple visual cues and requires minimal to no code changes for integration. It offers a portable API accessible via npm, CDN script tags, or a command-line interface, making it versatile for various development workflows across different React frameworks. The package is currently at version 0.5.3 and maintains an active development cycle with a moderate release cadence, though previous versions noted a period of slower releases. Key features include highlighting re-rendering components, providing notifications for performance issues, and offering a persistent, draggable toolbar for inspection.

npm install react-scan
INSTALL
IMPORT
SIG · REACT-SCAN
R
react-scan
observabilityjavascriptv0.5.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

scan
import { scan } from 'react-scan';
const scan = require('react-scan').scan;
This is the primary named export for development environments. For production or universal environments, use the subpath import 'react-scan/all-environments'.
scan (all-environments)
import { scan } from 'react-scan/all-environments';
import { scan } from 'react-scan';
Use this specific subpath import when `scan()` needs to be active in both development and production, or in environments where the default import might cause issues (e.g., error logging in production).
Options
import { Options } from 'react-scan';
type Options = any;
This is the TypeScript interface for configuring `react-scan`'s behavior, including enabling/disabling scanning, debugging, and notification settings.

This quickstart demonstrates how to integrate React Scan into a React application, enabling it conditionally for development environments. It shows the basic `scan()` function call with an `Options` object, and a simple React component structure that would trigger re-renders visible via the React Scan toolbar.

import { scan, Options } from 'react-scan'; import React, { useState, useEffect } from 'react'; import ReactDOM from 'react-dom/client'; // Define options for React Scan, typically enabling it only in development. const scanOptions: Options = { enabled: process.env.NODE_ENV === 'development', // Crucial for conditional activation debug: false, // Set to true for verbose logging // You can add more options like filters or thresholds here. }; // Initialize React Scan. It's best practice to call it once early in your app lifecycle. // Ensure this runs only client-side if your environment is universal (SSR/SSG). if (typeof window !== 'undefined') { scan(scanOptions); } function App() { const [count, setCount] = useState(0); useEffect(() => { console.log('App component mounted or re-rendered'); }); return ( <div> <h1>React Scan Basic Example</h1> <p>Current count: {count}</p> <button onClick={() => setCount(prev => prev + 1)}> Increment Count </button> <ChildComponent value={count} /> </div> ); } function ChildComponent({ value }: { value: number }) { // This component will re-render whenever its 'value' prop changes. // React Scan will highlight it and report its renders if enabled. return ( <p>Child component showing value: {value}</p> ); } // Render your application using ReactDOM. const rootElement = document.getElementById('root'); if (rootElement) { const root = ReactDOM.createRoot(rootElement); root.render( <React.StrictMode> <App /> </React.StrictMode> ); } else { console.error("Root element not found! Ensure an element with id='root' exists in your HTML."); }
react-scan --version
Debug
Known issues
breakingThe 'state change timeline' feature was temporarily removed in version 0.3.0 due to a bug in the 'what's changed' view. It may be re-introduced in a future release.
fix
No direct fix; the feature was intentionally removed. Developers should be aware of its absence and rely on other available inspection features.
affects: >=0.3.0
gotchaPrior to version 0.3.3, `react-scan` incorrectly attributed hot module reloading events as FPS drops, leading to false-positive performance notifications in the toolbar.
fix
Upgrade `react-scan` to version `0.3.3` or newer to resolve the misattribution of hot reloading events as performance issues.
affects: <0.3.3
breakingCalling the default `scan()` export in a production build or non-development environment prior to v0.3.6 could lead to errors being logged. This was fixed by introducing a specific import path.
fix
For production or universal environments, use the subpath import: `import { scan } from 'react-scan/all-environments';`. This import is designed to work correctly in all environments.
affects: <0.3.6
gotchaVersion 0.4.0 introduced a significant UI/UX change, allowing the React Scan toolbar to be 'thrown' off the page to hide it. This state persists across reloads.
fix
Users should be aware of the new drag-to-hide functionality. If the toolbar seems 'missing', it might have been thrown off-page. Dragging from the edge of the screen can restore it.
affects: >=0.4.0
breakingA memory leak was identified and fixed in version 0.4.3, specifically when interacting with the page many times while `react-scan` was active.
fix
Upgrade `react-scan` to version `0.4.3` or higher to benefit from the memory leak fix and ensure stable performance during extended debugging sessions.
affects: <0.4.3
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'scan') or similar errors when `scan()` is called in production.
Using the default `import { scan } from 'react-scan';` in a production build or non-development environment where it's not intended to run, or where its internal environment checks fail.
fix
For production or universal usage (where `scan()` needs to be active in all environments), explicitly use the subpath import: `import { scan } from 'react-scan/all-environments';`.
React Scan is constantly notifying about FPS drops or re-renders during hot module reloading, even when there's no actual performance issue.
Older versions of `react-scan` (prior to v0.3.3) incorrectly identified hot reloading events as performance degradation, leading to false-positive notifications.
fix
Upgrade `react-scan` to version `0.3.3` or a later version. This update includes a fix that prevents the tool from misinterpreting hot reloads.
The React Scan toolbar is obstructing my view and I cannot easily minimize or hide it, especially in versions before 0.4.0.
Prior to version 0.4.0, the `react-scan` toolbar had limited options for being hidden or minimized, making it intrusive for some workflows.
fix
Upgrade `react-scan` to version `0.4.0` or higher. This version introduced the ability to 'throw' the toolbar off the edge of the screen, which hides it and persists across reloads.
Upgrade
Version history
0.5.3latest on npm
Audit
Dependencies
reactrequiredRequired for React component introspection and integration, enabling the tool to observe and report on render cycles.
react-domrequiredRequired for React DOM manipulation and rendering hooks, essential for attaching the scanning mechanisms and visual overlays.
Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
2
Resources
react-scan — npm install react-scan · libregistry