repository·main·Indexed 12 days ago
https://github.com/aidenybai/react-scanA performance monitoring tool that automatically detects and highlights unnecessary React component re-renders. It includes a visual UI for identifying bottlenecks, a CLI for scanning local or remote websites, a headless instrumentation package (react-scan/lite), and a Vite plugin (@react-scan/vite-plugin-react-scan) for seamless integration.
react-scan/lite package. This is intended for automated testing or programmatic performance analysis where visual highlights are not required.To use React Scan in a React Router v7 project via a CDN, add a <script> tag to your Layout component within app/root.
Note: This method only works for React 19.
Refer to the project's CDN Guide for available URLs.
// app/root
// ...
export function Layout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<head>
<script src="https://unpkg.com/react-scan/dist/auto.global.js" />
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<Meta />
<Links />
</head>
<body>
{children}
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}
// ...You can add React Scan to your Remix application by adding a script tag to your <Layout> component in app/root.
Important:
https://unpkg.com/react-scan/dist/auto.global.js).// app/root.jsx
import {
Links,
Meta,
Scripts,
ScrollRestoration,
} from "@remix-run/react";
export function Layout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<head>
{/* Must run before any of your scripts */}
<script src="https://unpkg.com/react-scan/dist/auto.global.js" />
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<Meta />
<Links />
</head>
<body>
{children}
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}To quickly initialize React Scan without a build step or package manager, you can include the auto.global.js script directly in your HTML. This script automatically initializes the scanner.
<script src="https://cdn.jsdelivr.net/npm/react-scan/dist/auto.global.js"></script>In Next.js using the Pages Router, add the script inside your pages/_document.tsx within the Head component using next/script with the beforeInteractive strategy.
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>
);
}To use React Scan in a React Router v7 project via npm/import, follow these requirements:
scan from react-scan before React, React DOM, or React Router. This is necessary because React Scan needs to hijack React DevTools before they are accessed by the renderers.scan() inside a useEffect hook in your app/root component to ensure it only runs after hydration.import { scan } from "react-scan" for default behavior (typically development).import { scan } from "react-scan/all-environments" if you want React Scan to run in production as well.// app/root
// Must be imported before React Router
import { scan } from "react-scan";
import { Links, Meta, Scripts, ScrollRestoration } from "react-router";
import { useEffect } from "react";
export function Layout({ children }) {
useEffect(() => {
// Make sure to run react-scan only after hydration
scan({
enabled: true,
});
}, []);
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<Meta />
<Links />
</head>
<body>
{children}
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}// app/root
// Must be imported before React Router
import { scan } from "react-scan";
import { Links, Meta, Scripts, ScrollRestoration } from "react-router";
import { useEffect } from "react";
export function Layout({ children }) {
useEffect(() => {
scan({
enabled: true,
});
}, []);
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<Meta />
<Links />
</head>
<body>
{children}
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}To use React Scan in a Create React App (CRA) project without using module imports, add a script tag to the <head> section of your index.html.
Refer to the CDN Guide for the available URLs.
<!doctype html>
<html lang="en">
<head>
<script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
<!-- rest of your scripts go under -->
</head>
<body>
<!-- ... -->
</body>
</html>Alternatively, you can initialize React Scan directly in your app/entry.client.jsx file. This is a valid approach for React 19 applications.
Important: Call scan({ enabled: true }) before the hydration process begins.
// app/entry.client.jsx
import { RemixBrowser } from "@remix-run/react";
import { StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { scan } from "react-scan";
scan({
enabled: true,
});
// Hydration must happen in sync!
hydrateRoot(
document,
<StrictMode>
<RemixBrowser />
</StrictMode>
);You can manually initialize React Scan in your project entrypoint (e.g., src/main.jsx or src/index.jsx).
CRITICAL: You must import scan from react-scan before importing React or any other React renderers (like react-dom). This is necessary because React Scan needs to hijack React DevTools before React initializes them.
To enable scanning in production environments, use the react-scan/all-environments import path instead of the default react-scan path.
// src/index
import { scan } from "react-scan"; // must be imported before React and React DOM
import React from "react";
scan({
enabled: true,
});To ensure react-scan runs in production environments, change your import statement to use the all-environments entry point.
Standard import (development only):
import { scan } from "react-scan";
Production-ready import:
import { scan } from "react-scan/all-environments";
- import { scan } from "react-scan";
+ import { scan } from "react-scan/all-environments";To use React Scan in a Next.js App Router project using a script tag, add the script to the <head> section of your app/layout.js (or .tsx) file. This method uses a global script from a CDN.
Refer to the CDN Guide for the list of available URLs.
// app/layout
export default function RootLayout({ children }) {
return (
<html lang="en">
<head>
<script src="https://unpkg.com/react-scan/dist/auto.global.js" />
{/* rest of your scripts go under */}
</head>
<body>{children}</body>
</html>
);
}For standard HTML or Vite projects, paste the following script tag into your index.html before any other scripts:
<!-- paste this BEFORE any scripts -->
<script
crossOrigin="anonymous"
src="//unpkg.com/react-scan/dist/auto.global.js"
></script>