react-perf-mon v1.1.4
React Performance Monitor
A lightweight, easy-to-use performance monitoring library for React applications. Track render counts, mount times, update times, and identify unnecessary renders to optimize your React components.
Features
- 📊 Component Performance Metrics: Track render counts, mount times, update times, and total render time
- 🔍 Unnecessary Render Detection: Identify components that re-render when props haven't changed
- 📈 Real-time Performance Dashboard: Visualize performance metrics with a built-in, real-time updating dashboard
- 🚦 Threshold Warnings: Set thresholds for render counts and render times to get warnings
- 🔄 HOC & Hook API: Use either Higher-Order Components or hooks based on your preference
- 🧩 Context Bridge: Seamlessly connects monitoring and visualization contexts
- 🛡️ Error Handling: Gracefully handles errors to prevent application crashes
- 🔎 Component Filtering: Filter and search through monitored components in the dashboard
- 🔄 Metric Reset: Reset performance metrics at any time with a single click
Installation
npm install react-perf-mon
# or
yarn add react-perf-mon
Quick Start
1. Wrap your application with the PerformanceMonitoringProvider
import { PerformanceMonitoringProvider, PerformanceDashboard } from 'react-perf-mon';
function App() {
const [showDashboard, setShowDashboard] = useState(false);
return (
<PerformanceMonitoringProvider
config={{
enabled: true,
logToConsole: true,
includeWarnings: true,
thresholds: {
maxRenderCount: 10,
maxMountTime: 50, // ms
maxUpdateTime: 25 // ms
}
}}
>
<div className="App">
<button onClick={() => setShowDashboard(!showDashboard)}>
{showDashboard ? 'Hide' : 'Show'} Dashboard
</button>
{/* Your application components */}
<YourComponents />
{/* Conditionally render the dashboard */}
{showDashboard && <PerformanceDashboard />}
</div>
</PerformanceMonitoringProvider>
);
}
2. Track component performance using HOC (Recommended)
import { withPerformanceTracking } from 'react-perf-mon';
// Your component
const MyComponent = ({ name }) => {
return <div>Hello, {name}!</div>;
};
// Wrap with performance tracking
export default withPerformanceTracking(MyComponent, 'MyComponent');
3. Or track using hooks
import { useTrackPerformance } from 'react-perf-mon';
const MyComponent = ({ name }) => {
// Track this component's performance
useTrackPerformance('MyComponent');
return <div>Hello, {name}!</div>;
};
export default MyComponent;
Performance Dashboard
The PerformanceDashboard
component provides a comprehensive, real-time view of your application's performance metrics:
Key Metrics
- Components Tracked: Total number of components being monitored
- Total Renders: Cumulative count of render operations across all components
- Total Render Time: Aggregate rendering time across all components
- Unnecessary Renders: Number of renders that could have been avoided
Component-Level Metrics
For each tracked component, the dashboard displays:
- Component name
- Render count
- Mount time (ms)
- Total render time (ms)
- Unnecessary renders
- Average update time (ms)
Features
- Real-time Updates: Metrics update automatically as your components render
- Component Filtering: Search and filter components by name
- Metric Reset: Reset all metrics with a single click
- Sorting: Components are automatically sorted by total render time
- Responsive Design: Works well on all screen sizes
import { PerformanceDashboard } from 'react-perf-mon';
// Render the dashboard anywhere within the PerformanceMonitoringProvider
<PerformanceDashboard />
Configuration Options
The PerformanceMonitoringProvider
accepts the following configuration options:
interface PerformanceMonitorConfig {
enabled?: boolean; // Enable/disable tracking (default: true)
logToConsole?: boolean; // Log metrics to console (default: false)
includeWarnings?: boolean; // Enable threshold warnings (default: true)
excludeComponents?: string[]; // Components to exclude from tracking
thresholds?: {
maxRenderCount?: number; // Maximum acceptable render count
maxMountTime?: number; // Maximum acceptable mount time (ms)
maxUpdateTime?: number; // Maximum acceptable update time (ms)
};
}
Advanced Usage
Tracking Lazy-Loaded Components
import { withPerformanceTracking } from 'react-perf-mon';
import React, { lazy, Suspense } from 'react';
// Create your component
const MyLazyComponentContent = () => {
return <div>I'm lazy loaded!</div>;
};
// Wrap with performance tracking BEFORE lazy loading
const TrackedLazyComponent = withPerformanceTracking(MyLazyComponentContent, 'LazyComponent');
// Create lazy component
const LazyComponent = React.lazy(() =>
import('./path/to/component').then(module => ({
default: TrackedLazyComponent
}))
);
// Use with Suspense
function App() {
return (
<Suspense fallback={<div>Loading...</div>}>
<LazyComponent />
</Suspense>
);
}
Custom Metric Subscribers
You can subscribe to performance metrics directly using the usePerformanceMonitorContext
hook:
import { usePerformanceMonitorContext } from 'react-perf-mon';
const MetricLogger = () => {
const { subscribe } = usePerformanceMonitorContext();
useEffect(() => {
const unsubscribe = subscribe({
onMetricUpdate: (metric) => {
// Do something with the metric
console.log(`${metric.componentName} rendered in ${metric.lastRenderTime}ms`);
},
onWarning: (warning) => {
// Handle warnings
console.warn(`Warning: ${warning.componentName} ${warning.type} exceeded threshold`);
},
onReset: () => {
// Handle metrics reset
console.log('All metrics have been reset');
}
});
return unsubscribe;
}, [subscribe]);
return null;
};
Accessing Metrics Programmatically
You can access performance metrics directly using the usePerformanceContext
hook:
import { usePerformanceContext } from 'react-perf-mon';
const PerformanceAnalytics = () => {
const { metrics } = usePerformanceContext();
// Access metrics for a specific component
const buttonMetrics = metrics.components['Button'];
// Access the slowest component
const slowestComponent = metrics.slowestComponent;
// Do something with the metrics...
return null;
};
Troubleshooting
Context Provider Order
If you encounter errors like usePerformanceContext must be used within a PerformanceProvider
, ensure that your application is properly wrapped with the PerformanceMonitoringProvider
component. The library handles the correct nesting of context providers internally.
Performance Impact
The library is designed to have minimal impact on your application's performance. However, if you notice any performance issues, you can:
- Disable tracking for specific components using the
excludeComponents
option - Disable the library entirely by setting
enabled: false
in the config - Only enable the library in development or testing environments
Hook vs HOC
While both the hook (useTrackPerformance
) and HOC (withPerformanceTracking
) approaches are supported, the HOC approach is generally more reliable and recommended for most use cases. The HOC approach:
- Works better with class components
- Has better error handling
- Is less prone to issues with hook rules
- Provides more accurate unnecessary render detection
Best Practices
Use in Development: Consider enabling the library only in development or testing environments to avoid any performance impact in production.
Selective Tracking: Only track components that you're interested in monitoring, rather than tracking every component in your application.
Meaningful Component Names: Provide meaningful names when using
withPerformanceTracking
oruseTrackPerformance
to make the dashboard more useful.Exclude Fast Components: Use the
excludeComponents
option to exclude components that update very frequently and don't need monitoring.Adjust Thresholds: Adjust the warning thresholds based on your application's performance requirements.
Example Project
Check out the example project in the example
directory to see the library in action. It demonstrates various performance scenarios and how to use the library to monitor them.
License
MIT