why-render-react 0.1.0 → 1.0.1

package/README.md

@@ -1,27 +1,18 @@
-# Why Render
+# why-render-react
 
-React DevTools shows that something re-rendered. Why Render shows you why.
+A tiny React hook that logs **why** a component re-rendered — which props changed, what their previous and next values were, or whether nothing changed at all (meaning the re-render came from state, context, or a parent re-rendering).
 
-Add `useWhyRerender` to any component and get a console diff of exactly which props changed since the last render, so you can immediately tell whether a re-render was caused by a real prop change — or something else entirely.
+It's built for the common, easy-to-miss case: a prop that *looks* the same but is actually a brand-new object, array, or function on every render.
 
-## Table of Contents
+## Features
 
-- [Install](#install)
-- [Setup](#setup)
-  - [Wiring up global setup](#wiring-up-global-setup)
-- [Usage](#usage)
-- [Options](#options)
-- [Examples](#examples)
-  - [1. Basic component usage](#1-basic-component-usage)
-  - [2. A component whose props change](#2-a-component-whose-props-change)
-  - [3. A component that re-renders without its props changing](#3-a-component-that-re-renders-without-its-props-changing)
-  - [4. Inspecting previous and next values with `verbose`](#4-inspecting-previous-and-next-values-with-verbose)
-  - [5. Temporarily disabling tracking for one component](#5-temporarily-disabling-tracking-for-one-component)
-  - [6. A realistic parent/child example](#6-a-realistic-parentchild-example)
-- [Expected Output](#expected-output)
-- [Troubleshooting](#troubleshooting)
+- Zero-config logging of re-render causes, per component
+- Shows exactly which props changed
+- Optional `verbose` mode with previous/next values
+- Per-component `isActive` toggle to silence noisy components without disabling everything
+- One-line global `setup()` — works in dev, can be disabled in production
 
-## Install
+## Installation
 
 ```bash
 npm install why-render-react
@@ -29,95 +20,78 @@ npm install why-render-react
 
 ## Setup
 
-Why Render is off by default. Call `setup()` once, before your app renders, to turn it on:
+Call `setup()` once, before your app renders:
 
-```ts
+```tsx
+// index.tsx
 import { setup } from "why-render-react"
+import { createRoot } from "react-dom/client"
+import App from "./App"
 
 setup(true)
-```
-
-`setup()` also accepts strings, so you can wire it to an environment variable:
-
-```ts
-setup(process.env.USE_WHY_RENDER) // enabled only if the value is "true" (case-insensitive)
-```
-
-Pass `false` (or leave it unset) to keep Why Render off:
 
-```ts
-setup(false)
+createRoot(document.getElementById("root")!).render(<App />)
 ```
 
-This is a one-time, app-wide switch — call it once at your entry point, not inside individual components.
-
-> **Important:** if any component calls `useWhyRerender` before `setup()` has run, it will throw an error. Always call `setup()` first.
-
-### Wiring up global setup
-
-`setup()` only needs to run once for your whole app — typically in your entry file, before rendering:
+`setup()` takes a boolean (or anything that resolves to one, like an environment variable). A falsy value — `setup(false)`, a missing env var, or a typo like `"tru"` — silently disables logging entirely.
 
 ```tsx
-// main.tsx
-import { setup } from "why-render-react"
-import { createRoot } from "react-dom/client"
-import App from "./App"
-
 setup(process.env.NODE_ENV !== "production")
-
-createRoot(document.getElementById("root")!).render(<App />)
 ```
 
-Every component that calls `useWhyRerender` anywhere in the tree will start (or stop) logging based on that single call. *(full file: [`examples/00-setup.tsx`](./examples/00-setup.tsx))*
-
-## Usage
+## Basic Usage
 
-Add `useWhyRerender` inside any component you want to debug, passing it a name and that component's current props:
+Call `useWhyRerender` inside any component you want to watch, passing a `name` and the `props` you want tracked:
 
 ```tsx
+// CarCard.tsx
 import { useWhyRerender } from "why-render-react"
 
+interface CarCardProps {
+  color: string
+}
+
 function CarCard(props: CarCardProps) {
   useWhyRerender({ name: "CarCard", props })
-
   return <div>{props.color}</div>
 }
-```
 
-It's a React hook, so it follows the same rules as other hooks — call it unconditionally, at the top level of your component. Every time `CarCard` renders, Why Render logs what changed (or didn't) since the last render.
-
-## Options
-
-`useWhyRerender` takes a single options object:
-
-| Option       | Type        | Required | Default   | What it does                                                                                  |
-| ------------ | ----------- | -------- | --------- | --------------------------------------------------------------------------------------------- |
-| `name`     | `string`  | Yes      | —        | The label shown for this component in the console output.                                     |
-| `props`    | `object`  | Yes      | —        | The component's current props to track.                                                       |
-| `verbose`  | `boolean` | No       | `false` | Also logs each changed prop's previous and next value.                                        |
-| `isActive` | `boolean` | No       | `true`  | Set to`false` to turn off logging for just this component, without affecting anything else. |
-
-> Note: the field is `isActive`. If your editor or docs show `isActivate` anywhere, that's an internal naming detail — the option you pass is `isActive`.
+export default CarCard
+```
 
 ## Examples
 
-### 1. Basic component usage
+### 1. First render
 
-*(full file: [`examples/01-basic-usage.tsx`](./examples/01-basic-usage.tsx))*
+Nothing to compare yet, so it just logs the mount.
 
 ```tsx
+import { useWhyRerender } from "why-render-react"
+
+interface CarCardProps {
+  color: string
+}
+
 function CarCard(props: CarCardProps) {
   useWhyRerender({ name: "CarCard", props })
-
   return <div>{props.color}</div>
 }
+
+export default CarCard
 ```
 
-### 2. A component whose props change
+**Output:**
+
+```
+[why-rerender] <CarCard> render #1 → initial mount
+```
 
-*(full file: [`examples/02-props-change.tsx`](./examples/02-props-change.tsx))*
+### 2. A prop actually changes
 
 ```tsx
+import { useState } from "react"
+import { useWhyRerender } from "why-render-react"
+
 function CarCard({ color }: { color: string }) {
   useWhyRerender({ name: "CarCard", props: { color } })
   return <div>{color}</div>
@@ -125,7 +99,6 @@ function CarCard({ color }: { color: string }) {
 
 function Garage() {
   const [color, setColor] = useState("blue")
-
   return (
     <>
       <button onClick={() => setColor("red")}>Repaint</button>
@@ -133,17 +106,25 @@ function Garage() {
     </>
   )
 }
+
+export default Garage
 ```
 
-Clicking "Repaint" changes `color` and re-renders `CarCard`. The console shows `color` as the prop that changed — confirming the re-render was caused by that prop.
+**Output** (click "Repaint" — the line expands to show details):
 
-### 3. A component that re-renders without its props changing
+```
+▶ [why-rerender] <CarCard> render #3 → 1 prop changed
+    CHANGED   color
+```
 
-Components can re-render for reasons that have nothing to do with their own props — most commonly, because their parent re-rendered. This is exactly the case Why Render helps you catch:
+### 3. Re-render with no prop changes
 
-*(full file: [`examples/03-rerender-without-prop-change.tsx`](./examples/03-rerender-without-prop-change.tsx))*
+The parent re-renders (e.g. from unrelated state), but the child's props never change.
 
 ```tsx
+import { useState } from "react"
+import { useWhyRerender } from "why-render-react"
+
 function CarCard({ color }: { color: string }) {
   useWhyRerender({ name: "CarCard", props: { color } })
   return <div>{color}</div>
@@ -151,72 +132,133 @@ function CarCard({ color }: { color: string }) {
 
 function Garage() {
   const [, forceTick] = useState(0)
-
   return (
     <>
-      {/* Re-renders Garage (and CarCard) every second, but color never changes */}
+      {/* Re-renders Garage (and CarCard) on every click, but color never changes */}
       <button onClick={() => forceTick((t) => t + 1)}>Refresh</button>
       <CarCard color="blue" />
     </>
   )
 }
+
+export default Garage
 ```
 
-Clicking "Refresh" re-renders `Garage`, which re-renders `CarCard` even though `color` is still `"blue"`. Why Render logs that no props changed on that render — telling you to look at the parent, state, or context instead of the props.
+**Output:**
 
-### 4. Inspecting previous and next values with `verbose`
+```
+[why-rerender] <CarCard> render #4 → no prop changes — check state, context, or parent re-render
+```
 
-*(full file: [`examples/04-verbose.tsx`](./examples/04-verbose.tsx))*
+### 4. Verbose mode
+
+Set `verbose: true` to see the previous and next values alongside each changed prop.
 
 ```tsx
+import { useState } from "react"
+import { useWhyRerender } from "why-render-react"
+
 function CarCard({ color }: { color: string }) {
   useWhyRerender({ name: "CarCard", props: { color }, verbose: true })
   return <div>{color}</div>
 }
+
+function Garage() {
+  const [color, setColor] = useState("blue")
+  return (
+    <>
+      <button onClick={() => setColor("red")}>Repaint</button>
+      <CarCard color={color} />
+    </>
+  )
+}
+
+export default Garage
 ```
 
-With `verbose: true`, each changed prop's previous and next value is included in the output, so you don't have to guess what it changed *from* and *to*.
+**Output:**
 
-### 5. Temporarily disabling tracking for one component
+```
+▶ [why-rerender] <CarCard> render #3 → 1 prop changed
+    CHANGED   color   { prev: "blue", next: "red" }
+```
+
+### 5. Silencing one noisy component
 
-*(full file: [`examples/05-disable-instance.tsx`](./examples/05-disable-instance.tsx))*
+If a single component logs too often to debug around, set `isActive: false` on that one instead of disabling `setup()` for the whole app.
 
 ```tsx
+import { useWhyRerender } from "why-render-react"
+
+interface NoisyWidgetProps {
+  cursorX: number
+  cursorY: number
+}
+
 function NoisyWidget(props: NoisyWidgetProps) {
   useWhyRerender({ name: "NoisyWidget", props, isActive: false })
-  return (/* ... */)
+  return (
+    <div>
+      {props.cursorX},{props.cursorY}
+    </div>
+  )
 }
-```
 
-Use this when one component re-renders constantly (e.g. on every keystroke) and its logging is drowning out everything else. Setting `isActive: false` only silences `NoisyWidget` — `setup()` stays enabled, and every other component's `useWhyRerender` call keeps logging normally:
-
-```tsx
-function Dashboard(props: DashboardProps) {
-  useWhyRerender({ name: "Dashboard", props }) // still logs
+function Sidebar(props: { title: string }) {
+  useWhyRerender({ name: "Sidebar", props })
+  return <aside>{props.title}</aside>
+}
 
+function Dashboard(props: { title: string }) {
+  useWhyRerender({ name: "Dashboard", props })
   return (
     <>
-      <Sidebar {...sidebarProps} />          {/* still logs */}
-      <NoisyWidget {...widgetProps} />        {/* silenced */}
+      <Sidebar title={props.title} />        {/* still logs */}
+      <NoisyWidget cursorX={0} cursorY={0} /> {/* silenced */}
     </>
   )
 }
+
+export default Dashboard
 ```
 
-### 6. A realistic parent/child example
+### 6. The hidden cause: a new function every render
 
-*(full file: [`examples/06-parent-child.tsx`](./examples/06-parent-child.tsx))*
+This is the case `why-render-react` is best at catching. `CarList` passes a brand-new `onSelect` arrow function to every `CarCard` on every render. Even though `id` and `color` might not have changed, `onSelect` is a *different value* in JavaScript each time — so Why Render correctly flags it as changed.
 
 ```tsx
-function CarCard({ id, color, onSelect }: CarCardProps) {
-  useWhyRerender({ name: "CarCard", props: { id, color, onSelect }, verbose: true })
+import { useState } from "react"
+import { useWhyRerender } from "why-render-react"
+
+interface Car {
+  id: number
+  color: string
+}
 
+interface CarCardProps {
+  id: number
+  color: string
+  onSelect: (id: number) => void
+}
+
+function CarCard({ id, color, onSelect }: CarCardProps) {
+  useWhyRerender({
+    name: "CarCard",
+    props: { id, color, onSelect },
+    verbose: true,
+  })
   return <div onClick={() => onSelect(id)}>{color}</div>
 }
 
 function CarList({ cars }: { cars: Car[] }) {
   const [selectedId, setSelectedId] = useState<number | null>(null)
 
+  const setId = (id: number) => {
+    if (selectedId !== id) {
+      setSelectedId(id)
+    }
+  }
+
   return (
     <>
       {cars.map((car) => (
@@ -224,67 +266,84 @@ function CarList({ cars }: { cars: Car[] }) {
           key={car.id}
           id={car.id}
           color={car.color}
-          // A new function is created on every CarList render, so this prop
-          // "changes" on every render even though the click behavior is the same.
-          onSelect={(id) => setSelectedId(id)}
+          // New function every render -> onSelect always shows as "changed"
+          onSelect={(id) => setId(id)}
         />
       ))}
     </>
   )
 }
-```
 
-Every time `CarList` re-renders (e.g. when `selectedId` changes), each `CarCard` gets a brand-new `onSelect` function. Why Render flags `onSelect` as changed on every render — a common, easy-to-miss cause of unnecessary re-renders that's hard to spot just by eyeballing the code.
-
-## Expected Output
+export default CarList
+```
 
-**First render — nothing to compare yet:**
+**Output:**
 
 ```
-[why-rerender] <CarCard> render #1 → initial mount
+▶ [why-rerender] <CarCard> render #2 → 1 prop changed
+    CHANGED   onSelect   { prev: "ƒ", next: "ƒ" }
 ```
 
-**A later render where a prop actually changed** (this line expands to show details):
+**The fix** — memoize the handler with `useCallback` so the same function reference is reused across renders:
 
-```
-▶ [why-rerender] <CarCard> render #3 → 1 prop changed
-    CHANGED   color
-```
+```tsx
+import { useState, useCallback } from "react"
+import { useWhyRerender } from "why-render-react"
 
-With `verbose: true`, the same line also includes the previous and next values:
+function CarList({ cars }: { cars: Car[] }) {
+  const [selectedId, setSelectedId] = useState<number | null>(null)
 
-```
-▶ [why-rerender] <CarCard> render #3 → 1 prop changed
-    CHANGED   color   { prev: "blue", next: "red" }
+  const setId = useCallback((id: number) => {
+    setSelectedId((current) => (current !== id ? id : current))
+  }, [])
+
+  return (
+    <>
+      {cars.map((car) => (
+        <CarCard key={car.id} id={car.id} color={car.color} onSelect={setId} />
+      ))}
+    </>
+  )
+}
 ```
 
-**A render where no props changed** (see [Example 3](#3-a-component-that-re-renders-without-its-props-changing)):
+## API Reference
 
-```
-[why-rerender] <CarCard> render #4 → no prop changes — check state, context, or parent re-render
-```
+### `setup(enabled: boolean)`
 
-## Troubleshooting
+Enables or disables all Why Render logging globally. Must be called once, before your app renders.
+
+### `useWhyRerender(options)`
 
-**Error: "WhyRenderConfig has not been configured"** — `setup()` hasn't run yet. Call it once, before your app renders (see [Setup](#setup)).
+| Option    | Type                  | Required | Default | Description                                                                 |
+|-----------|-----------------------|----------|---------|-------------------------------------------------------------------------------|
+| `name`    | `string`               | Yes      | —       | Label shown in the console log for this component.                          |
+| `props`   | `object`               | Yes      | —       | The props (or any values) to track for changes.                             |
+| `isActive`| `boolean`              | No       | `true`  | Set to `false` to silence logging for just this component.                  |
+| `verbose` | `boolean`              | No       | `false` | Includes previous/next values for each changed prop in the log.             |
 
-**Nothing is logging, and no error was thrown** — check:
+## Troubleshooting
 
-1. `setup()` was actually called with a value that resolves to enabled — `setup(false)`, a missing environment variable, or a typo like `"tru"` will silently disable it.
-2. That component's call doesn't have `isActive: false` set (see [Example 5](#5-temporarily-disabling-tracking-for-one-component)).
+**Error: `"WhyRenderConfig has not been configured"`**
+`setup()` hasn't run yet. Call it once, before your app renders (see [Setup](#setup)).
 
-**One component is too noisy to debug around** — set `isActive: false` on that component instead of disabling `setup()` for the whole app.
+**Nothing is logging, and no error was thrown**
+Check the following:
+- `setup()` was actually called with a value that resolves to `true` — `setup(false)`, a missing environment variable, or a typo like `"tru"` will silently disable it.
+- That component's call doesn't have `isActive: false` set (see [Example 5](#5-silencing-one-noisy-component)).
+- If one component is too noisy to debug around, set `isActive: false` on that component instead of disabling `setup()` for the whole app.
 
-**A prop keeps showing as "changed" even though it looks the same** — this usually means a new object, array, or function is being created for that prop on every render (see [Example 6](#6-a-realistic-parentchild-example)). Since these are different values in JavaScript even when their contents look identical, Why Render correctly reports them as changed.
+**A prop keeps showing as "changed" even though it looks the same**
+This usually means a new object, array, or function is being created for that prop on every render (see [Example 6](#6-the-hidden-cause-a-new-function-every-render)). Since these are different values in JavaScript even when their contents look identical, Why Render correctly reports them as changed.
 
-# License
+## License
 
-### MIT License
+MIT License
 
-Copyright (c) why-render contributors
+Copyright (c) why-render-react contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "why-render-react",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "A React hook that helps you understand why a component re-rendered.",
   "types": "module",
   "main": "dist/index.js",