react-debug-updates

See exactly which React components re-render, how often, how long they take, and why — all without modifying your components.

Created and used at Screen Studio.

Why?

I needed to debug React re-render performance in an Electron app, but I could never get the official React DevTools to work with Electron. The integration is fragile, poorly documented, and breaks between versions. I just needed to see which components were re-rendering.

So I wrote this — a plug-and-play one-liner that gives you visual highlight overlays and console logging for React re-renders. No browser extension, no Electron hacks, no configuration. Works in any React web environment — browsers, Electron, iframes.

How it works

Hooks into __REACT_DEVTOOLS_GLOBAL_HOOK__ to intercept every React commit. Detects re-rendered components using the exact same fiber tree diffing approach as the official React DevTools — following their original implementation of didFiberRender and parallel tree walking. No React DevTools extension required. No wrappers, no HOCs, no code changes — just call startReactUpdatesMonitor() and you get:

• Visual highlights — highlight boxes on re-rendered DOM nodes with a heat-map color scale (blue → red as render count increases)
• Console logging — grouped, color-coded re-render reports with component tree paths and render durations
• Update reasons — pinpoint which useState, useReducer, useSyncExternalStore, or useContext hook triggered each re-render, with previous→next values

Install

npm install react-debug-updates
# or
yarn add react-debug-updates
# or
pnpm add react-debug-updates

Quick start

Import and call startReactUpdatesMonitor before React renders anything — ideally at the very top of your entry point. This ensures the hook is in place before the first commit.

import { startReactUpdatesMonitor } from "react-debug-updates";

// One-liner — visual highlights out of the box
const stop = startReactUpdatesMonitor();

// Later, to clean up:
stop();

Dev-only guard

if (process.env.NODE_ENV === "development") {
  const { startReactUpdatesMonitor } = await import("react-debug-updates");
  startReactUpdatesMonitor();
}

With options

startReactUpdatesMonitor({
  reasonOfUpdate: true,
  logToConsole: true,
  highlightOpacity: 0.5,
  highlightShowLabels: false,
});

Requirements

• A React dev build (which automatically creates __REACT_DEVTOOLS_GLOBAL_HOOK__) — no browser extension needed
• For reasonOfUpdate and render durations: React must be in dev mode (provides _debugHookTypes and actualDuration on fibers)

API

startReactUpdatesMonitor(options?): () => void

Returns a stop function to unhook from React and remove all overlays. Throws if called in a non-browser environment (e.g. SSR).

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | mode | "self-triggered" \| "all" | "self-triggered" | "self-triggered" tracks only components whose own state changed. "all" includes children swept by parent updates | | reasonOfUpdate | boolean | false | Detect and display why each component re-rendered | | logToConsole | boolean | false | Log re-renders to the console | | highlight | boolean | true | Enable visual highlight overlays | | highlightShowLabels | boolean | true | Show text labels (name, count, duration, cause) above highlights | | highlightOpacity | number | 0.8 | Peak opacity of highlight overlays (0–1) | | highlightFlushInterval | number | 250 | Milliseconds between highlight flush cycles | | highlightAnimationDuration | number | 1200 | Highlight fade-out animation duration (ms) |

UpdateCause

| Property | Type | Description | | --- | --- | --- | | kind | "hook" \| "props" \| "class-state" \| "unknown" | Category of the cause | | hookIndex | number? | Source-order index of the hook (0-based) | | hookType | string? | e.g. "useState", "useReducer", "useContext" | | previousValue | unknown? | Previous hook state value | | nextValue | unknown? | New hook state value |

Console output

⚛ 3 re-renders
  Counter  App → Dashboard (0.42ms)
    ↳ useState[0]: 5 → 6
  TodoList  App → Dashboard (1.03ms)
    ↳ props changed (parent re-rendered)
  Sidebar  App (0.15ms)
    ↳ useContext changed

Visual highlights

Re-rendered components get a highlight box that fades out. The color shifts from blue to red as the same node re-renders repeatedly within a flush window — making "hot" components visually obvious.

Each highlight label shows: ComponentName ×count duration (cause)

License

MIT