Dev-only performance guardrail for React and Next.js using React Profiler
npm install react-perf-guardCatch performance issues before they reach production



Quick Start ⢠Features ⢠Documentation ⢠Examples
---
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.
---
| 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.
---
$3Monitors component renders without manual profiling sessions | $3Detects performance degradation through trend analysis | $3Confidence-based system prevents false positives |
$3Boundary-aware severity tuning for accurate reporting | $3Suppresses one-off spikes and repetitive warnings | $3Visual dashboard for tracking issues in real-time |
$3Automatically disabled in production builds | $3Analysis runs off-thread for zero impact | $3Works with Next.js, Create React App, Vite |
---
āāāāāāāāāāāāāāāāāāāāāāā
ā 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
`bash
Using npm
npm install react-perf-guardUsing pnpm
pnpm add react-perf-guardUsing yarn
yarn add react-perf-guard
`Requirements:
- React 16.8+ (Hooks support)
- Development environment (automatically disabled in production)
---
š Quick Start
$3
The
PerfProvider is the entry point that initializes the performance monitoring system.`tsx
import { PerfProvider } from "react-perf-guard";export function App() {
return (
);
}
`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.---
$3
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.
`tsx
import { withPerfGuard } from "react-perf-guard";function HeavyComponent() {
return
Heavy UI rendering logic;
}// Wrap and export
export default withPerfGuard(HeavyComponent);
`#### šØ Option B ā
PerfProfiler Component WrapperGreat for explicit profiling or conditional instrumentation.
`tsx
import { PerfProfiler } from "react-perf-guard";export function ProductPage() {
return (
);
}
`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.
$3
- 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
$3
- 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.
$3
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
$3
- š“ 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 |
$3
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.
$3
`
Current Render Snapshot + Historical Data
ā
Declarative Rule Evaluation
ā
Pattern & Trend Detection
ā
Confidence Score Calculation
ā
Issue Classification
`$3
- š 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.
$3
`tsx
// 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
}
`$3
- 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
$3
react-perf-guard works seamlessly with both Next.js routing paradigms.
#### š Pages Router
Wrap your application in
_app.tsx:`tsx
import type { AppProps } from "next/app";
import { PerfProvider } from "react-perf-guard";export default function MyApp({ Component, pageProps }: AppProps) {
return (
);
}
`#### šļø App Router
Create a client-side provider component:
`tsx
// app/providers.tsx
"use client";import { PerfProvider } from "react-perf-guard";
import { ReactNode } from "react";
export function Providers({ children }: { children: ReactNode }) {
return {children} ;
}
`Then use it in your root layout:
`tsx
// app/layout.tsx
import { Providers } from "./providers";export default function RootLayout({ children }) {
return (
{children}
);
}
`$3
- 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:
$3
- 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
$3
- 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.
$3
`bash
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! ā