render-peek 🫣

Stop guessing. Start seeing. A lightweight React Hook that visually exposes unnecessary re-renders in real-time.

Why render-peek?

React performance issues are often invisible. Components re-render silently, eating up CPU cycles and draining battery, often due to:

• ❌ New object references passed as props (e.g., style={{}} or inline functions).
• ❌ Parent updates that shouldn't affect the child.
• ❌ Broken React.memo comparisons.

Console logs are noisy. React DevTools is powerful but heavy.

render-peek gives you immediate, visual feedback right in your UI. If a component re-renders but its props haven't actually changed (deep equality), it flashes orange.

It's like a Geiger counter for wasted renders.

Features

• 🔦 Visual Feedback: A subtle orange flash on unnecessary re-renders.
• 🧠 Smart Comparison: Uses deep equality to detect when props are technically new but semantically identical.
• 🙈 Ignore Noise: Easily ignore unstable props (like inline callbacks) that trigger false positives.
• 🪶 Zero Config: Just import and use. Styles are injected automatically.
• 📦 Tiny: < 2kb gzipped.

Installation

npm install render-peek
# or
yarn add render-peek
# or
pnpm add render-peek

Usage

1. Basic Usage

Wrap your component's props with useRenderPeek. If the component re-renders but props are unchanged, it will flash.

import { useRenderPeek } from 'render-peek';

export const UserCard = (props) => {
  // 1. Hook into the render cycle
  const { className } = useRenderPeek(props);

  return (
    // 2. Apply the class to your root element
    <div className={`card ${className}`}>
      <h2>{props.name}</h2>
    </div>
  );
};

2. Ignoring Unstable Props (Common Scenario)

Often you pass inline functions (callbacks) that are recreated on every render. These are changes, but you might not care about them for performance tuning. Use ignoreKeys to skip them.

// Parent passes a new arrow function every time:
// <Button onClick={() => handleClick()} />

export const Button = (props) => {
  const { className } = useRenderPeek(props, {
    // Ignore 'onClick' so it doesn't trigger a "valid" change detection
    ignoreKeys: ['onClick'] 
  });

  // Now, if 'onClick' changes but other props are stable, 
  // render-peek will see it as an "unnecessary" render and FLASH.
  
  return <button className={className} {...props} />;
};

How to Interpret the Flash

• No Flash:
  • Either the component didn't render (good!).
  • Or it rendered because props actually changed (good!).
• 🟠 Orange Flash:
  • The component rendered, BUT the props (excluding ignored ones) are deeply equal to the previous render.
  • Action: This is a candidate for React.memo, useMemo, or fixing the parent's prop passing.

Production Usage 🛡️

render-peek is designed as a development tool. You typically shouldn't ship it to production users.

To safely leave it in your codebase without affecting production, create a wrapper hook:

// hooks/useRenderPeek.ts
import { useRenderPeek as useOriginalPeek } from 'render-peek';

export const useRenderPeek = (props: any, options?: any) => {
  // In production, return an empty object so it does nothing
  if (process.env.NODE_ENV === 'production') {
    return { className: '' };
  }
  
  return useOriginalPeek(props, options);
};

Now you can use your custom useRenderPeek everywhere. It will work in dev and be silent in prod.

License

MIT