{"id":11848,"library":"react-scan","title":"React Scan","description":"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.","status":"active","version":"0.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/aidenybai/react-scan","tags":["javascript","react","react-scan","react scan","render","performance","typescript"],"install":[{"cmd":"npm install react-scan","lang":"bash","label":"npm"},{"cmd":"yarn add react-scan","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-scan","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for React component introspection and integration, enabling the tool to observe and report on render cycles.","package":"react","optional":false},{"reason":"Required for React DOM manipulation and rendering hooks, essential for attaching the scanning mechanisms and visual overlays.","package":"react-dom","optional":false}],"imports":[{"note":"This is the primary named export for development environments. For production or universal environments, use the subpath import 'react-scan/all-environments'.","wrong":"const scan = require('react-scan').scan;","symbol":"scan","correct":"import { scan } from 'react-scan';"},{"note":"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).","wrong":"import { scan } from 'react-scan';","symbol":"scan (all-environments)","correct":"import { scan } from 'react-scan/all-environments';"},{"note":"This is the TypeScript interface for configuring `react-scan`'s behavior, including enabling/disabling scanning, debugging, and notification settings.","wrong":"type Options = any;","symbol":"Options","correct":"import { Options } from 'react-scan';"}],"quickstart":{"code":"import { scan, Options } from 'react-scan';\nimport React, { useState, useEffect } from 'react';\nimport ReactDOM from 'react-dom/client';\n\n// Define options for React Scan, typically enabling it only in development.\nconst scanOptions: Options = {\n enabled: process.env.NODE_ENV === 'development', // Crucial for conditional activation\n debug: false, // Set to true for verbose logging\n // You can add more options like filters or thresholds here.\n};\n\n// Initialize React Scan. It's best practice to call it once early in your app lifecycle.\n// Ensure this runs only client-side if your environment is universal (SSR/SSG).\nif (typeof window !== 'undefined') {\n scan(scanOptions);\n}\n\nfunction App() {\n const [count, setCount] = useState(0);\n\n useEffect(() => {\n console.log('App component mounted or re-rendered');\n });\n\n return (\n
\n

React Scan Basic Example

\n

Current count: {count}

\n \n \n
\n );\n}\n\nfunction ChildComponent({ value }: { value: number }) {\n // This component will re-render whenever its 'value' prop changes.\n // React Scan will highlight it and report its renders if enabled.\n return (\n

Child component showing value: {value}

\n );\n}\n\n// Render your application using ReactDOM.\nconst rootElement = document.getElementById('root');\nif (rootElement) {\n const root = ReactDOM.createRoot(rootElement);\n root.render(\n \n \n \n );\n} else {\n console.error(\"Root element not found! Ensure an element with id='root' exists in your HTML.\");\n}\n","lang":"typescript","description":"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."},"warnings":[{"fix":"No direct fix; the feature was intentionally removed. Developers should be aware of its absence and rely on other available inspection features.","message":"The '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.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Upgrade `react-scan` to version `0.3.3` or newer to resolve the misattribution of hot reloading events as performance issues.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.3.3"},{"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.","message":"Calling 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.","severity":"breaking","affected_versions":"<0.3.6"},{"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.","message":"Version 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.","severity":"gotcha","affected_versions":">=0.4.0"},{"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.","message":"A memory leak was identified and fixed in version 0.4.3, specifically when interacting with the page many times while `react-scan` was active.","severity":"breaking","affected_versions":"<0.4.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'scan') or similar errors when `scan()` is called in production."},{"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.","cause":"Older versions of `react-scan` (prior to v0.3.3) incorrectly identified hot reloading events as performance degradation, leading to false-positive notifications.","error":"React Scan is constantly notifying about FPS drops or re-renders during hot module reloading, even when there's no actual performance issue."},{"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.","cause":"Prior to version 0.4.0, the `react-scan` toolbar had limited options for being hidden or minimized, making it intrusive for some workflows.","error":"The React Scan toolbar is obstructing my view and I cannot easily minimize or hide it, especially in versions before 0.4.0."}],"ecosystem":"npm"}