SpeedAct

A simple and efficient library for monitoring React component performance.

Installation

npm install speedact

Quick Start

Wrapper Component

import { PerformanceMonitor } from "speedact";

function App() {
  return (
    <PerformanceMonitor
      componentName="MyComponent"
      logToConsole={true}
      threshold={16} // Alert if render > 16ms
      onMetricsUpdate={(metrics) => console.log(metrics)}
    >
      <MyComponent />
    </PerformanceMonitor>
  );
}

API Reference

PerformanceMonitor

Available props:

• children: ReactNode - Child components to be monitored
• componentName?: string - Component name (default: "PerformanceMonitor")
• onMetricsUpdate?: (metrics: PerformanceMetrics) => void - Callback called on each render
• logToConsole?: boolean - Automatic console logging (default: false)
• threshold?: number - Threshold in ms for alerts (default: 16)
• enabled?: boolean - Enable/disable monitoring (default: true)
• maxSamples?: number - Maximum renders tracked (default: 100)

PerformanceMetrics

interface PerformanceMetrics {
  renderCount: number;
  totalRenderTime: number;
  averageRenderTime: number;
  longestRenderTime: number;
  shortestRenderTime: number;
  lastRenderTime: number;
  componentName?: string;
  timestamp: number;
}

Utilities

PerformanceUtils

import { PerformanceUtils } from "speedact";

// Get metrics for a specific component
PerformanceUtils.getComponentMetrics("ComponentName");

// Get all monitored component names
PerformanceUtils.getAllComponentNames();

// Get metrics for all components
PerformanceUtils.getAllMetrics();

// Reset metrics for a specific component
PerformanceUtils.resetComponentMetrics("ComponentName");

// Reset all metrics
PerformanceUtils.resetAllMetrics();

// Generate global report
PerformanceUtils.generateGlobalReport();

// Get active components count
PerformanceUtils.getActiveComponentsCount();

// Force cleanup all data
PerformanceUtils.forceCleanup();

Performance Grading

Components are automatically graded based on average render time:

• A: < 16ms (60fps capable)
• B: 16-33ms (30fps capable)
• C: 33-50ms (20fps capable)
• D: > 50ms (poor performance)

Examples

Basic Monitoring

import { PerformanceMonitor } from "speedact";

function App() {
  return (
    <PerformanceMonitor componentName="App" logToConsole={true}>
      <YourComponent />
    </PerformanceMonitor>
  );
}

Monitoring with Callback

import { PerformanceMonitor, PerformanceMetrics } from "speedact";

function App() {
  const handleMetricsUpdate = (metrics: PerformanceMetrics) => {
    if (metrics.lastRenderTime > 16) {
      console.warn(`Slow render detected: ${metrics.lastRenderTime}ms`);
    }
  };

  return (
    <PerformanceMonitor
      componentName="App"
      onMetricsUpdate={handleMetricsUpdate}
      threshold={16}
    >
      <YourComponent />
    </PerformanceMonitor>
  );
}

Conditional Monitoring

import { PerformanceMonitor } from "speedact";

function App() {
  const isDevelopment = process.env.NODE_ENV === "development";

  return (
    <PerformanceMonitor
      componentName="App"
      enabled={isDevelopment}
      logToConsole={isDevelopment}
    >
      <YourComponent />
    </PerformanceMonitor>
  );
}

Advanced Usage with Reports

import { PerformanceMonitor, PerformanceUtils } from "speedact";

function App() {
  const generateReport = () => {
    // Get metrics for specific component
    const metrics = PerformanceUtils.getComponentMetrics("App");
    console.log("App metrics:", metrics);

    // Generate and display global report
    const report = PerformanceUtils.generateGlobalReport();
    console.log(report);
  };

  return (
    <div>
      <button onClick={generateReport}>Generate Report</button>
      <PerformanceMonitor componentName="App" threshold={16}>
        <YourComponent />
      </PerformanceMonitor>
    </div>
  );
}

How It Works

SpeedAct uses React's Profiler API to accurately measure component render times. The library:

1. Measures each render using performance.now()
2. Stores metrics in an efficient circular buffer
3. Calculates statistics automatically (average, max, min)
4. Provides analysis and performance grading

Library Performance

• 📦 Small: ~3.5KB gzipped
• ⚡ Fast: Minimal performance overhead
• 🔄 Efficient: Circular buffer for memory management
• 🛡️ Safe: Robust error handling
• 🧹 Clean: Automatic cleanup of unused components

Features

• ✅ Simple API: Only wrapper component approach
• ✅ TypeScript: Full TypeScript support with complete type definitions
• ✅ Performance grading: Automatic A-D grading system
• ✅ Console logging: Optional automatic logging with emoji indicators
• ✅ Memory efficient: Circular buffer prevents memory leaks
• ✅ Flexible thresholds: Configurable performance thresholds
• ✅ Detailed metrics: Comprehensive render statistics
• ✅ Production ready: Minimal overhead, can be safely used in production

Browser Compatibility

• React >= 16.8.0
• TypeScript >= 4.0.0
• Modern browsers with Performance API support
• Gracefully degrades in older browsers

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Repository

https://github.com/renatokhael/speedact