React Debug Overlay

In-app React debugging overlay for renders, prop diffs, network activity, runtime errors, inspect mode, and event correlation.

This project currently contains two parts:

• A TypeScript library built from src/
• A Vite playground app used to exercise the overlay locally

Current MVP

• Toggleable in-app overlay via enableDebugOverlay()
• Render tracking with useDebugTrack()
• Prop diff snapshots for tracked components
• fetch and XMLHttpRequest logging
• Runtime error capture for console.error, uncaught errors, and unhandled rejections
• Inspect mode for tracked components
• Grouped and filtered render feed
• Unified timeline across renders, network, and errors
• Timeline search plus selected-component scope mode
• Click-to-pin for render, timeline, network, and error events
• Export/import of debug snapshots
• Persisted overlay UI preferences
• Playground app for local testing

Install

Local development:

npm install

Published package usage:

npm install react-debug-overlay

Scripts

npm run dev
npm run build
npm run build:playground
npm run preview:playground
npm run clean

Script meanings:

• npm run dev: start the Vite playground in development mode
• npm run build: build the library from src/ using tsup
• npm run build:playground: build the playground app into playground-dist/
• npm run preview:playground: preview the built playground output
• npm run clean: remove generated library and playground build output

Basic Usage

Enable the overlay in development:

import { enableDebugOverlay } from "react-debug-overlay";

enableDebugOverlay();

Track a component and attach the returned ref to a DOM node:

import { useDebugTrack } from "react-debug-overlay";

type ProfileCardProps = {
  name: string;
  online: boolean;
};

export function ProfileCard(props: ProfileCardProps) {
  const debugRef = useDebugTrack("ProfileCard", props);

  return (
    <section ref={debugRef}>
      <h2>{props.name}</h2>
      <p>{props.online ? "online" : "offline"}</p>
    </section>
  );
}

Overlay API

enableDebugOverlay(options?)

Creates the overlay once and returns a controller.

Relevant options today:

• hotkey: keyboard shortcut, defaults to Alt+D
• title: overlay title
• trackNetwork: enable fetch and XHR logging
• trackErrors: enable runtime error capture
• zIndex: overlay z-index
• initialDock: one of bottom-right, bottom-left, top-right, top-left
• initialSize: one of compact, default, expanded
• initialRenderFilter: initial render filter text
• initialRenderGrouping: initial render grouping state
• initialTimelineFilter: one of all, renders, network, errors
• initialTimelineQuery: initial timeline search text
• initialTimelineSelectedOnly: show only timeline entries tied to the selected tracked component
• persistPreferences: whether overlay UI preferences are stored in localStorage
• preferencesStorageKey: localStorage key override
• maxNetworkEntries: retained network items
• maxErrorEntries: retained error items

Current overlay behavior:

• inspect tracked components in-app
• filter and group render activity
• correlate renders, requests, and errors in the timeline
• pin render, network, error, and timeline items
• export a snapshot to JSON and import it later
• persist overlay UI preferences across reloads

Programmatic snapshot API

The returned controller now exposes a scriptable snapshot API:

const controller = enableDebugOverlay();

const snapshot = controller.exportSnapshot();

if (snapshot) {
  localStorage.setItem("overlay-snapshot", JSON.stringify(snapshot));
}

const saved = localStorage.getItem("overlay-snapshot");

if (saved) {
  controller.importSnapshot(JSON.parse(saved)); // boolean return value
}

controller.importSnapshotFromJson(saved ?? ""); // convenience helper

controller.resetSnapshot(); // back to live mode

Controller methods

const controller = enableDebugOverlay();

controller.show();
controller.hide();
controller.toggle();
controller.exportSnapshot();
controller.importSnapshot(snapshot);
controller.importSnapshotFromJson(snapshotJson);
controller.resetSnapshot();
controller.destroy();

useDebugTrack(name, props)

Tracks renders for a React component and returns a ref that must be attached to a DOM element.

What it records:

• Render count
• Changed prop keys
• Previous vs current prop values
• Serialized prop snapshot

Playground

The local playground lives under playground/ and imports the library source through a Vite alias, so you can iterate on the package without publishing anything.

Typical workflow:

npm install
npm run dev

Then open the local Vite URL, press Alt+D, and use the playground buttons to trigger:

• component rerenders
• network requests
• console errors
• unhandled promise rejections

The overlay also supports:

• pinning entries directly from the render, timeline, network, and error panels
• exporting the current viewed session as JSON
• importing a saved snapshot and switching the overlay into snapshot mode

Current Limitations

• Component tracking is opt-in through useDebugTrack
• Inspect mode only works for tracked components with attached refs
• Network and error retention is in-memory only
• Snapshot APIs are intentionally minimal and currently limited to full overlay payloads
• The package README assumes a local or future npm release; repository and issue metadata are not configured yet

Project Layout

src/
  errors/
  inspect/
  network/
  overlay/
  react/
playground/

Next Work

• add package repository metadata once the remote repo exists
• add richer examples and screenshots
• test install flow from a clean external React app