react-debug-flow

A dev-only React hook that tells you exactly why your component re-rendered — in plain English.

The problem

You add a console.log inside a component. It fires 6 times. You stare at React DevTools. You Google "why is my component re-rendering". Sound familiar?

// React DevTools shows you a tree. Not helpful.
// why-did-you-render dumps a raw object diff. Hard to read.
// Neither tells you what it actually MEANS.

The solution

One line. Drop it in any component:

import { useDebugFlow } from 'react-debug-flow';

function UserCard({ userId, filters, onSelect }) {
  useDebugFlow('UserCard', { userId, filters, onSelect });
  // ...
}

A floating badge appears directly on your component:

┌─────────────────────────────────────────────────┐
│  <UserCard>  render #3                          │
│─────────────────────────────────────────────────│
│  component   <UserCard>                         │
│  renders     #3                                 │
│  reason      `onSelect` is a new function       │
│              reference — wrap it in useCallback │
│  changed     `onSelect`                         │
└─────────────────────────────────────────────────┘

Zero config. Zero runtime dependencies. Automatically stripped in production.

Install

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

Usage

Basic — useDebugFlow hook

import { useDebugFlow } from 'react-debug-flow';

function ProductList({ filters, page, onPageChange }) {
  const overlay = useDebugFlow('ProductList', { filters, page, onPageChange });

  return (
    <div style={{ position: 'relative' }}>
      {overlay}
      {/* rest of your JSX */}
    </div>
  );
}

Console mode

Prefer your browser console over an overlay?

useDebugFlow('MyComponent', props, { output: 'console' });
// or show both at once
useDebugFlow('MyComponent', props, { output: 'both' });

Global config — DebugFlowProvider

Set defaults once at your app root so you don't repeat options everywhere:

import { DebugFlowProvider } from 'react-debug-flow';

export default function App() {
  return (
    <DebugFlowProvider config={{ output: 'console', maxHistory: 20 }}>
      <YourApp />
    </DebugFlowProvider>
  );
}

HOC — withDebugFlow

For class components, or when you can't edit the component source:

import { withDebugFlow } from 'react-debug-flow';

const DebuggedList = withDebugFlow(MyList, 'MyList');
// Use <DebuggedList /> exactly like <MyList />

Custom callback — onRender

Pipe render info into your own logging or analytics system:

useDebugFlow('Dashboard', props, {
  output: 'console',
  onRender: (info) => {
    console.table(info.changedProps);
  },
});

API Reference

useDebugFlow(componentName, props?, options?)

| Parameter | Type | Description | |---|---|---| | componentName | string | Name shown in the overlay and console | | props | Record<string, unknown> | The component's props to track | | options | DebugFlowOptions | Per-component config (overrides Provider) |

Returns React.ReactElement | null — render the returned value inside your component to show the overlay.

DebugFlowOptions

| Option | Type | Default | Description | |---|---|---|---| | output | 'overlay' \| 'console' \| 'both' | 'overlay' | Where to surface debug info | | maxHistory | number | 10 | How many renders to keep in memory | | highlight | boolean | true | Flash a border on each re-render | | collapsed | boolean | false | Start the overlay collapsed | | onRender | (info: RenderInfo) => void | undefined | Custom callback fired on every render |

RenderInfo

interface RenderInfo {
  componentName: string;
  renderCount:   number;
  changedProps:  { key: string; prev: unknown; next: unknown }[];
  reason:        string;   // plain English — e.g. "`userId` changed (1 → 2)"
  timestamp:     number;
}

Production safety

Every code path is guarded by:

if (process.env.NODE_ENV === 'production') return null;

Modern bundlers (Vite, webpack, esbuild, Parcel) tree-shake this to zero bytes in your production bundle. You never need to remove it before shipping.

How it compares

| | React DevTools | why-did-you-render | react-debug-flow | |---|:---:|:---:|:---:| | Browser extension required | ✅ | ❌ | ❌ | | In-app visual overlay | ❌ | ❌ | ✅ | | Plain English explanations | ❌ | ❌ | ✅ | | Beginner-friendly output | ❌ | ❌ | ✅ | | Warns about unstable function props | ❌ | partial | ✅ | | Works in CI / test output | ❌ | ✅ | ✅ | | Zero runtime dependencies | ✅ | ✅ | ✅ |

Contributing

PRs and issues are welcome!

git clone https://github.com/abdullah-al-monir/react-debug-flow
cd react-debug-flow
npm install
npm run dev    # build in watch mode
npm test       # run tests

License

MIT © Abdullah Al Monir