⚡ React Performance Advisor

An enterprise-grade, full-stack React & Network performance monitoring tool powered by AI.

React Performance Advisor acts as an "X-ray machine" for your web applications. It hooks directly into React's native Virtual DOM and the Browser's low-level W3C Performance API to catch unnecessary re-renders, prop instability, slow API calls, and poor Web Vitals — then uses AI to instantly write the code to fix them.

---

✨ Features

⚛️ Virtual DOM Diagnostics (React)

• 🧠 AI-Powered Code Fixes — Automatically streams context (render counts, lag time, changed props) to Gemini to generate exact useMemo, useCallback, or Web Worker code fixes.
• ⏱️ Main-Thread Blocking — Utilizes React's native <Profiler> to catch components taking >16ms to render, saving your 60FPS frame rate.
• 🔍 Deep Prop Tracking — Performs strict equality checks to catch "Object/Function Reference Traps" causing silent cascading re-renders.

🌐 Browser Engine Diagnostics (Network & Vitals)

• 📡 Network API WatchDog — Bypasses React entirely to monitor the browser's raw network engine. Automatically catches slow fetch/XHR requests and heavy assets taking >500ms.
• 🎨 Core Web Vitals (FCP) — Automatically tracks your First Contentful Paint. If your initial UI takes longer than 1.5 seconds to draw, it flags the bottleneck.
• 🤖 Full-Stack AI Doctor — Generates actionable architectural fixes for network lag (e.g., implementing React Query, pagination, caching, or lazy loading).

---

🦠 The 6 Bugs We Catch

#	Bug	Description
1	Object Reference Traps	Inline {} objects breaking child memoization
2	Inline Function Traps	Anonymous () => {} functions missing useCallback
3	Wasted Render Avalanches	50+ children re-rendering for a single parent state change
4	Heavy Commits	Synchronous calculations blocking the main thread
5	High-Latency APIs	Slow backend requests and heavy >5MB image/bundle payloads
6	Poor Web Vitals	Slow First Contentful Paint (FCP) blocking initial page load

---

📦 Installation

npm install react-performance-advisor

---

🚀 Quick Start

1. Wrap your suspect components

Import PerformanceAdvisor and wrap it around the components you want to monitor. Give it a unique id.

Note: Mounting just one of these automatically activates the global Network WatchDog!

import { PerformanceAdvisor } from 'react-performance-advisor';
import { MyHeavyComponent } from './MyHeavyComponent';

function App() {
  return (
    <div>
      <h1>My Dashboard</h1>

      {/* Wrap the component to track React renders AND start the Network WatchDog */}
      <PerformanceAdvisor id="HeavyDashboard">
        <MyHeavyComponent data={someData} />
      </PerformanceAdvisor>
    </div>
  );
}

2. Add the AI Panel

Drop PerformanceAdvisorPanel anywhere in your top-level App.tsx file.

import { PerformanceAdvisorPanel } from 'react-performance-advisor';

function App() {
  return (
    <div>
      {/* ... your app code ... */}

      {/* Drop the panel at the bottom of your app */}
      <PerformanceAdvisorPanel />
    </div>
  );
}

3. Diagnose!

1. Run your app in development mode.
2. Interact with your app — if a component re-renders unnecessarily, or an API request takes too long, a warning will instantly appear in the floating panel.
3. Click "✨ Ask AI How to Fix This".
4. Enter your Gemini API key when prompted (it will be saved securely in your local storage).
5. Copy and paste the AI's optimized code directly into your editor!

---

⚠️ Note on React Strict Mode

If you are running React 18+ in Development Mode with <React.StrictMode>, React intentionally double-renders components to catch side effects. This tool will accurately report both renders.

To see true single-render metrics, temporarily disable Strict Mode in your main.tsx or index.tsx:

// Before
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

// After (for accurate profiling)
root.render(<App />);

---

🛠️ How It Works

Layer	What Happens
React Engine	<PerformanceAdvisor> attaches React's native <Profiler> API to your component. It performs deep prop diffing on every render cycle.
Browser Engine	The useBrowserPerformance hook utilizes the W3C PerformanceObserver API to silently grade network requests and paint times directly from the V8 engine.
Aggregation	Both data streams are normalized, filtered for false positives, and surfaced in the floating <PerformanceAdvisorPanel>.
AI Resolution	One click streams the specific technical context to Gemini 2.5 Flash, which returns ready-to-paste code fixes and architectural strategies.

---

🔒 Security & Privacy

• Your API key is stored locally in your browser's localStorage.
• This package does not use an intermediate backend; it communicates directly with the Google Generative AI API.
• Your source code is never uploaded or analyzed outside of the specific prop names flagged in the UI.

---

📄 License

MIT © React Performance Advisor Contributors