who-changed-my-props 🕵️‍♂️

A lightweight React runtime utility to trace props changes and detect unnecessary re-renders - with style.

who-changed-my-props helps you monitor what triggers re-renders in your React components by:

• Logging which props changed
• Counting how many times a component re-rendered
• Emitting warnings when a threshold is exceeded
• Supporting custom logging (console, toast, websocket...)
• Offering a dev overlay that shows re-render activity in real time

🚀 Why use this tool?

React components re-render more often than we think. Sometimes that's fine. Sometimes... it’s killing performance silently.

Instead of guessing, let your components snitch on themselves.

Unlike heavier tools like why-did-you-render, this utility is:

• 🔹 Explicit: opt-in on a per-component basis
• 🔹 Framework-agnostic: no patching, no assumptions
• 🔹 Minimal: no global state, no Babel magic
• 🔹 Flexible: choose how and where logs appear

📦 Installation

npm install who-changed-my-props
# or
yarn add who-changed-my-props

🧑‍💻 Usage

1. Trace manually inside a component

import { traceProps } from 'who-changed-my-props';

function ChatInput(props) {
  traceProps('ChatInput', props, { warnThreshold: 5 });

  return <input value={props.value} onChange={props.onChange} />;
}

2. Wrap any component using withTrace

import { withTrace } from 'who-changed-my-props';

const TracedButton = withTrace(Button, 'Button', { warnThreshold: 3 });

⚙️ Custom Logger

import { setTraceLogger } from 'who-changed-my-props';

setTraceLogger({
  log: (...args) => console.log('[TRACE]', ...args),
  warn: (...args) => toast.warn(args.join(' ')) // use your preferred logger
});

👀 Dev Overlay

To see a visual overlay with re-render count:

import { createDevOverlay } from 'who-changed-my-props';

createDevOverlay(); // Call this once in your app root

🧪 Example Output

🔄 [ChatInput] props changed: { value: "hello", onChange: [Function] }
⚠️ [ChatInput] rendered 6 times (threshold: 5)

📘 API Reference

traceProps(name, props, options?)

| Param | Type | Description | |---------|----------|--------------------------------------| | name | string | Display name for logs | | props | object | The props object to track | | options.warnThreshold | number? | Trigger a warning after N renders |

withTrace(Component, name, options?)

Wraps any component and auto-instruments it.

setTraceLogger(logger)

Define a custom logging system.

createDevOverlay()

Displays an overlay in the corner of your screen with re-render count.

🙌 Ideal For

• Component performance debugging
• Auditing prop-based reactivity
• Creating a performance culture in frontend teams

🧠 Why not just use React DevTools?

You should. But when you want traceability inside your codebase, and the ability to log, count, warn and visualize in your own way - this tool gives you the reins.

🛠️ Roadmap

• [ ] Group renders by component tree
• [ ] Add live chart/graph mode to overlay
• [ ] Enable snapshot exports for CI

🧙 Author

Q. Ackermann – Senior Engineer, Toolmaker, Systems Thinker
GitHub | KodeReview | LinkedIn

📄 License

MIT