React Lifecycle Tracker

A powerful React package that helps you understand and visualize component lifecycle events, state changes, and performance metrics in your React application. Track renders, updates, and component behavior globally without adding hooks to every component.

Features

- 🔄 Automatic Tracking - No hooks needed in your components (optional hooks available)
- 📊 Visual Overlay - See lifecycle events in real-time with an interactive UI
- ⚡ Performance Metrics - Track render durations and phases
- 🎯 Global Context - Access events from anywhere using subscription pattern
- 🪶 Lightweight - Minimal overhead using React's Profiler API
- 🔍 Component Inspector - Click any component to see detailed state, props, and history
- 📈 Timeline View - Track state and props changes over time with before/after values
- 🎨 Color-Coded - Visual indicators for different update causes

Installation

``bash
npm install react-lifecycle-tracker

or

yarn add react-lifecycle-tracker
`

Quick Start

Wrap your app with the LifecycleTracker provider:

`jsx
import { LifecycleTracker } from 'react-lifecycle-tracker';

function App() {
return (
config={{
enabled: true,
showOverlay: true,
logToConsole: true,
}}
>


);
}
`

Component Tracking

Track individual components to see what causes re-renders:

`jsx
import { useComponentTracker } from 'react-lifecycle-tracker';

function MyComponent({ userId, theme }) {
const [count, setCount] = useState(0);
const [isActive, setIsActive] = useState(false);

// Track this component
useComponentTracker({
name: 'MyComponent',
props: { userId, theme },
state: { count, isActive }
});

return

...

;
}
`

Configuration

`jsx
config={{
enabled: true, // Enable/disable tracking
showOverlay: true, // Show visual overlay
logToConsole: false, // Log events to console
includeTimings: true, // Include performance timings
maxHistorySize: 50, // Max changes to keep in history
onEvent: (event) => { // Custom event handler
console.log(event);
},
onComponentUpdate: (update) => { // Custom component update handler
console.log(update);
}
}}
>


`

Overlay Features

$3

- Shows React Profiler events (mount/update/nested-update)
- Displays render duration in milliseconds
- Tracks all components in the tree automatically

$3

- Shows individual component updates with causes:
- 🟢 mount - Component first rendered
- 🟠 props-change - Props changed (shows which props)
- 🔵 state-change - Internal state changed
- 🟣 parent-render - Parent re-rendered
- 🔷 context-change - Context value changed
- Shows render count for each component
- Lists which props/state changed
- Click to expand - See detailed inspector view

$3

- Current Props - All current prop values
- State Timeline - Complete history of state changes with:
- Variable name
- Old value → New value (color-coded)
- Timestamp of change
- Props Timeline - Complete history of prop changes
- Update History - Last updates with causes and changes

Optional Hooks

While tracking happens automatically, you can optionally access events from within components:

`jsx
import { useLifecycleEvents } from 'react-lifecycle-tracker';

function MyComponent() {
const { events, clearEvents } = useLifecycleEvents();

return (

Total renders: {events.length}

Clear

);
}
`

Event Structure

$3

`typescript
interface LifecycleEvent {
id: string;
componentName: string;
phase: 'mount' | 'update' | 'nested-update';
timestamp: number;
duration: number;
baseDuration?: number;
startTime?: number;
interactions: Set;
}
`

$3

`typescript
interface ComponentUpdate {
componentName: string;
cause: 'mount' | 'props-change' | 'state-change' | 'parent-render' | 'context-change';
renderCount: number;
timestamp: number;
changedProps?: string[];
stateChanges?: string[];
currentProps?: Record;
currentState?: Record;
}
`

$3

`typescript
interface ValueChange {
key: string;
oldValue: unknown;
newValue: unknown;
timestamp: number;
}
`

Use Cases

- 🐛 Debugging - Understand why components re-render and track down issues
- 📚 Learning - Visualize React's lifecycle for educational purposes
- ⚡ Performance - Identify slow renders and optimization opportunities
- 🔍 Monitoring - Track component behavior in development
- 📊 Analysis - See how state and props evolve over time

TypeScript Support

Fully typed with TypeScript. All types are exported:

`typescript
import type {
LifecycleEvent,
ComponentUpdate,
TrackerConfig,
UpdateCause,
ComponentSnapshot,
ValueChange
} from 'react-lifecycle-tracker';
``

Performance

- Uses React's built-in Profiler API
- Subscription-based updates prevent unnecessary re-renders
- Configurable history size to manage memory
- Minimal overhead in production builds

Browser Support

Works with React 18+ and modern browsers that support:
- ES2017+
- React Profiler API
- useSyncExternalStore

License

MIT