⚡ react-perf-guard

Performance Guard for React Applications

Catch performance issues before they reach production

Quick Start • Features • Documentation • Examples

---

🎯 What is react-perf-guard?

react-perf-guard (Performance Guard) is a development-first performance guardrail for React applications that continuously monitors component rendering during development and automatically detects performance issues, regressions, and UX risks — before they ever reach production.

It's a dev-only runtime performance analysis tool that works silently in the background, applying a rule-based analysis engine to surface clear, actionable signals instead of noisy metrics.

Think of it as ESLint for runtime performance — continuous, automatic, and built for developers.

---

🤔 Why react-perf-guard?

❌ The Problem Today

• React DevTools Profiler requires manual intervention
• Lighthouse runs after performance degradation occurs
• Performance regressions slip through silently
• Console logs create noise and alert fatigue
• Teams lack continuous performance feedback
• Performance audits happen too late in the cycle

✅ The react-perf-guard Solution

• Automatic render performance detection
• Continuous monitoring during development
• Intelligent rule-based insights
• Deduplicated issue reporting
• Trend & regression detection
• Real-time performance feedback

How It's Different

Traditional Approach	react-perf-guard
Manual profiling sessions	✨ Automatic detection
One-time snapshots	📊 Continuous monitoring
Raw timing numbers	🎯 Rule-based insights
Console spam	🔕 Deduplicated issues
No historical data	📈 Trend & regression analysis
Post-development audits	🚀 Development-time prevention

Make performance a continuous development signal — not a last-minute crisis.

---

✨ Key Features

🚀 Automatic Detection Monitors component renders without manual profiling sessions	📉 Regression Analysis Detects performance degradation through trend analysis	🧠 Smart Rule Engine Confidence-based system prevents false positives
🎯 Context-Aware Boundary-aware severity tuning for accurate reporting	🔕 Noise-Resistant Suppresses one-off spikes and repetitive warnings	🖥️ Built-in Panel Visual dashboard for tracking issues in real-time
🔒 Production-Safe Automatically disabled in production builds	⚡ Worker-Based Analysis runs off-thread for zero impact	🎨 Framework-Friendly Works with Next.js, Create React App, Vite

---

🏗️ How react-perf-guard Works

┌─────────────────────┐
│  React Profiler     │  ← Captures component render metrics
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Metrics Collector   │  ← Batches data in-memory
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Batch Flush       │  ← Sends metrics at intervals
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Analyzer Web Worker │  ⚡ Runs off the main thread
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Rule Engine       │  ← Evaluates performance patterns
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Issue Aggregation   │  ← Deduplicates & prioritizes
└──────────┬──────────┘
           │
           ├──────────────┐
           ▼              ▼              
    ┌─────────┐   ┌──────────┐
    │  Panel  │   │  Alerts  │
    └─────────┘   └──────────┘

Architecture Overview:

1. React Profiler captures render metrics from instrumented components
2. Metrics Collector batches data in-memory for efficiency
3. Batch Flush sends accumulated metrics at intervals
4. Analyzer Web Worker processes data off the main thread
5. Rule Engine evaluates performance patterns against rules
6. Issue Aggregation deduplicates and prioritizes findings
7. PerfGuard Panel displays actionable insights to developers

All heavy analysis runs in a Web Worker, keeping your application fast and responsive.

---

📦 Installation

# Using npm
npm install react-perf-guard

# Using pnpm
pnpm add react-perf-guard

# Using yarn
yarn add react-perf-guard

Requirements:

• React 16.8+ (Hooks support)
• Development environment (automatically disabled in production)

---

🚀 Quick Start

1️⃣ Wrap Your App with PerfProvider

The PerfProvider is the entry point that initializes the performance monitoring system.

import { PerfProvider } from "react-perf-guard";

export function App() {
  return (
    <PerfProvider>
      <YourApp />
    </PerfProvider>
  );
}

What happens under the hood:

• ✅ Starts the analyzer worker thread
• ✅ Loads performance rules into the engine
• ✅ Begins automatic metric flushing
• ✅ Mounts the PerfGuard Panel UI

🔒 Production Safety: react-perf-guard automatically disables itself in production with zero overhead.

---

2️⃣ Instrument Components (optional but recommended)

Choose the approach that fits your code style. Both methods use React's built-in Profiler API internally.

🎨 Option A — withPerfGuard HOC (Higher-Order Component)

Perfect for wrapping existing components without modifying their structure.

import { withPerfGuard } from "react-perf-guard";

function HeavyComponent() {
  return <div>Heavy UI rendering logic</div>;
}

// Wrap and export
export default withPerfGuard(HeavyComponent);

🎨 Option B — PerfProfiler Component Wrapper

Great for explicit profiling or conditional instrumentation.

import { PerfProfiler } from "react-perf-guard";

export function ProductPage() {
  return (
    <PerfProfiler id="ProductList">
      <ProductList />
    </PerfProfiler>
  );
}

Best Practices:

• Instrument components at route/page boundaries
• Profile known performance-sensitive components
• Use descriptive IDs for easier debugging

---

🖥️ PerfGuard Panel

The PerfGuard Panel is your performance command center — a visual dashboard that appears automatically in development.

📊 What It Shows Active Issues: Current performance problems Resolved Issues: Previously fixed problems Severity Levels: LOW → MEDIUM → HIGH → CRITICAL Confidence Scores: Trend-based reliability indicator Component Names: Exact location of issues Rule IDs: Which performance rule was triggered Expandable Details: Full context and recommendations

🎯 Panel Features Real-time Updates: Issues appear as they're detected Issue Filtering: Focus on specific severity levels Historical View: Track resolution over time One-Click Details: Expand for full diagnostic info Minimal UI: Unobtrusive during development Auto-hidden: Never appears in production

The panel is your single source of truth for React performance issues during development.

---

🚨 Critical Alerts

When critical performance issues are detected, react-perf-guard escalates visibility to ensure you don't miss user-impacting problems.

What Makes an Issue "Critical"?

Critical issues indicate likely user-visible UX problems such as:

• Render times exceeding 100ms (blocking the main thread)
• Repeated severe performance degradation
• High-confidence regression detection

Critical Alert Behavior

• 🔴 Visually Highlighted: Red indicators in the panel
• 📢 Reported Once: Per component lifecycle to avoid spam
• 📌 Persistent Display: Remains visible until resolved
• 🎯 High Priority: Sorted to the top of the issue list

This prevents alert fatigue while ensuring serious regressions get immediate attention.

---

🎯 Boundary Types

Boundary types provide context-aware severity tuning — the same render time means different things for different component types.

Boundary Type	Description	Example Use Cases	Severity Adjustment
INLINE	Small child component	Buttons, icons, labels	Softened (higher threshold)
ROUTE	Page or route boundary	Full page components	Standard severity
LAYOUT	Layout or shell component	Navigation, sidebars, wrappers	Moderate severity

Why This Matters

A 50ms render might be:

• ✅ Acceptable for a route-level page component
• ⚠️ Concerning for a layout shell
• 🚨 Critical for an inline button

Boundary types ensure you get accurate, actionable signals instead of false alarms.

---

🧠 Rule Engine Overview

The rule engine is the brain of react-perf-guard, transforming raw metrics into actionable performance insights.

How Rules Work

Current Render Snapshot + Historical Data
              ↓
    Declarative Rule Evaluation
              ↓
    Pattern & Trend Detection
              ↓
  Confidence Score Calculation
              ↓
    Issue Classification

Key Characteristics

• 📋 Declarative Rules: Define what to look for, not how to find it
• 📊 Historical Context: Evaluates current performance against past trends
• 🎚️ Confidence-Based: Scores increase only when issues persist
• 🛡️ False Positive Prevention: Ignores one-off spikes and anomalies
• 🔄 Adaptive: Learns normal patterns for each component

Perfect for long development sessions and real feature work, not just contrived demos.

---

🔒 Production Safety Guarantee

react-perf-guard is designed with production safety as the top priority.

What Gets Disabled in Production

// Development: Full monitoring enabled
if (process.env.NODE_ENV === 'development') {
  // ✅ React Profiler active
  // ✅ Web Worker running
  // ✅ Rule engine processing
  // ✅ Dev Panel visible
  // ✅ Metrics collection active
}

// Production: Everything disabled
if (process.env.NODE_ENV === 'production') {
  // ❌ No React Profiler
  // ❌ No Web Worker
  // ❌ No Dev Panel
  // ❌ No memory overhead
  // ❌ No runtime cost
}

Zero Production Footprint

• No bundle size impact (tree-shaken away)
• No memory allocation for metrics
• No CPU cycles for analysis
• No network requests for reporting
• No visual components rendered

Safe by default. Zero cost in production. Guaranteed.

---

⚡ Framework Integration

Using with Next.js

react-perf-guard works seamlessly with both Next.js routing paradigms.

📄 Pages Router

Wrap your application in _app.tsx:

import type { AppProps } from "next/app";
import { PerfProvider } from "react-perf-guard";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <PerfProvider>
      <Component {...pageProps} />
    </PerfProvider>
  );
}

🗂️ App Router

Create a client-side provider component:

// app/providers.tsx
"use client";

import { PerfProvider } from "react-perf-guard";
import { ReactNode } from "react";

export function Providers({ children }: { children: ReactNode }) {
  return <PerfProvider>{children}</PerfProvider>;
}

Then use it in your root layout:

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Other Frameworks

• Create React App: Wrap in src/index.tsx
• Vite: Wrap in src/main.tsx
• Remix: Wrap in app/root.tsx

---

🛣️ Roadmap

We're actively developing features to make react-perf-guard even more powerful:

🔜 Coming Soon Custom Rule Authoring API Define your own performance rules and thresholds CI/CD Integration GitHub Actions support for automated performance checks Performance Budgets Set and enforce render time budgets per component

🔮 Future Vision Exportable Reports Generate performance reports for documentation Ignore Annotations Suppress specific warnings when intentional Dashboard Integrations Connect to monitoring platforms

Want to contribute? We welcome PRs and feature suggestions!

---

📚 Additional Resources

• Documentation: Full API Reference (coming soon)
• Examples: GitHub Examples Repository (coming soon)
• Blog: Performance Best Practices (coming soon)

---

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports
• 💡 Feature suggestions
• 📖 Documentation improvements
• 🔧 Code contributions

Please check our contributing guidelines before submitting a PR.

---

📄 License

MIT © Amiya Das

---

⭐ Final Word

Performance should fail early, clearly, and with context.

react-perf-guard transforms performance from a last-minute fire drill into a daily development habit.

Stop shipping performance regressions. Start building faster React apps.

Ready to guard your React performance?

npm install react-perf-guard

Get Started • View Examples • Read Docs

---

Made with ⚡ for React developers who care about performance

Star this repo if you find it useful! ⭐