React Performance HUD ⚡️

A lightweight, production-safe performance monitor for React applications.
Real-time tracking for JS Heap Usage, DOM Node Count, and Route-Change Memory Leaks.

✨ Features

• 🧠 Memory Monitoring: Real-time JS Heap usage (Chromium browsers)
• 🏗 DOM Node Counter: Works in all browsers (Recommended: Chrome or Edge)
• 🚦 Route Leak Detector: Detects memory added/removed per route navigation
• 🛡 Production Safe: Disabled automatically when NODE_ENV=production
• 🔋 Battery Friendly: Pauses when tab is backgrounded

📦 Installation

npm install react-performance-hud
# or
yarn add react-performance-hud

🚀 Usage

Basic Usage

Place the component at the root of your app:

import React from 'react';
import { MemoryHUD } from 'react-performance-hud';

function App() {
  return (
    <>
      <MemoryHUD />
      <YourApplication />
    </>
  );
}

2. Advanced Usage (With Route Tracking)

To track memory changes per route, you need to pass the dependency prop. Note: You must create a wrapper component so useLocation is called inside the Router.

import React from 'react';
import { BrowserRouter as Router, Routes, Route, useLocation } from 'react-router-dom';
import { MemoryHUD } from 'react-performance-hud';

// 1. Create a wrapper component
const PerformanceMonitor = () => {
  const location = useLocation();
  return <MemoryHUD dependency={location.pathname} />;
};

function App() {
  return (
    <Router>
      {/* 2. Place it inside the Router */}
      <PerformanceMonitor />
      
      <Routes>
        <Route path="/" element={<Home />} />
        {/* ... your other routes */}
      </Routes>
    </Router>
  );
}

export default App;

⚙️ Configuration

| Prop | Type | Default | Description | |----------------|---------|---------|-------------| | dependency | any | null | Calculates memory deltas on change | | memoryBudget | number | 128 | MB threshold before turning Yellow | | nodeBudget | number | 1500 | DOM node count threshold before turning Yellow | | intervalMs | number | 1000 | Polling interval (in milliseconds) | | forceEnable | boolean | false | Force display in production mode |

Example

<MemoryHUD
  memoryBudget={300}
  nodeBudget={2500}
/>

📊 Performance Indicators

| Level | Status | RAM Usage | DOM Nodes | Meaning | |-------------|-----------|---------------|--------------|-----------------------------| | 🟢 Green | Excellent | < 128 MB | < 1500 | Safe for low-end devices | | 🟡 Yellow | Caution | 128–256 MB | 1500–3000 | Risky on low-end devices | | 🔴 Red | Critical | > 256 MB | > 3000 | Fix leaks immediately |

📜 License

MIT © 2025 Vikas Sharma