react-render-spy

Render debugger for React components. It explains why a component re-rendered and gives practical optimization hints.

Features

• Hook (useRenderSpy) to track prop/state-like values.
• HOC (withRenderSpy) to instrument existing components quickly.
• Diff categories: added, removed, changed.
• Optimization hints for unstable function/object/array references.
• Configurable output (collapse groups, hide values, include/exclude keys, etc.).

Install

npm install react-render-spy

Quick Start

import { useRenderSpy } from "react-render-spy";

function ProfileCard(props: { user: { id: string }; onSave: () => void; count: number }) {
  useRenderSpy("ProfileCard", props);
  return <div>{props.count}</div>;
}

Usage

1) Hook usage

import { useRenderSpy } from "react-render-spy";

function ProductCard(props: { item: any; onAdd: () => void; count: number }) {
  useRenderSpy("ProductCard", props, {
    logOnMount: false,
    includeValues: true,
    collapseGroup: true,
  });

  return <div>{props.count}</div>;
}

2) Track state + derived values

import { useMemo, useState } from "react";
import { useRenderSpy } from "react-render-spy";

function Example({ items }: { items: string[] }) {
  const [query, setQuery] = useState("");
  const filtered = useMemo(
    () => items.filter((item) => item.includes(query)),
    [items, query],
  );

  useRenderSpy("Example", { items, query, filtered }, { includeValues: false });

  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

3) HOC usage

import { withRenderSpy } from "react-render-spy";

const Button = ({ onClick, label }: { onClick: () => void; label: string }) => (
  <button onClick={onClick}>{label}</button>
);

export default withRenderSpy(Button, "Button", {
  includeValues: true,
  maxEntries: 10,
});

API

useRenderSpy(componentName, trackedValues, options?)

• componentName: label shown in console.
• trackedValues: object of values to diff between renders (props, state, derived values).
• options:
  • enabled?: boolean - master on/off switch.
  • logOnMount?: boolean - include first render in logs.
  • includeValues?: boolean - include previous/next values in table.
  • collapseGroup?: boolean - use console.groupCollapsed.
  • maxEntries?: number - cap rows shown per render.
  • logUnchanged?: boolean - log when tracked values did not change.
  • includeKeys?: string[] - allowlist tracked keys.
  • excludeKeys?: string[] - denylist tracked keys.

withRenderSpy(Component, name?, options?)

Wraps a component and tracks incoming props automatically.

Output example

react-render-spy prints:

• Component name + render count
• Change type (added / removed / changed)
• Whether the change is a reference change
• A practical recommendation for likely optimization

Development

npm install
npm run build
npm run test:run

Release

See RELEASE.md for the complete publish checklist.

Notes

• Designed for development diagnostics.
• Keep object/function references stable (useMemo/useCallback) for best results.