react-component-usage-visualizer

A developer-focused React utility to visualize LIVE component usage, render reasons, prop/hook changes, and unused component alerts—all inside a real running app overlay panel. Works with both React.js and React Native.

🚀 Features

• 🔎 Live overlay panel: See in-app analytics and visualize component usage, renders, and prop change frequency
• 💡 Render reason inspector: Know why a component was re-rendered (prop, context, state)
• 🔗 Dependency/children graph: Show parent-child render chain as interactive tree
• 🧩 Hook activity tracker: Track which hooks activate and how often
• ⚠️ Unused/imported-but-inactive detector: Alert if a component never gets rendered
• 🎨 Heatmap/graph panel: Visualize component usage by route, frequency, or page
• 📊 Performance metrics: Get insights into render efficiency and optimization opportunities
• 📤 Export functionality: Export analytics data as JSON or CSV for further analysis
• 📱 React Native support: Full compatibility with React Native apps
• 🔄 Platform detection: Automatically detects and adapts to React.js or React Native

🎯 Why is it unique?

Existing solutions just show profiler graphs or component hierarchies (React DevTools, Storybook Docs), but NONE combine this overlay approach with per-render prop/hook analytics in a real running instance — especially not as a plug-and-play npm package for easy drop-in usage.

📦 Installation

npm install react-component-usage-visualizer

🚀 Quick Start

import React from 'react';
import { UsageDashboard, useComponentUsage } from 'react-component-usage-visualizer';

function MyApp() {
  useComponentUsage('MyApp'); // Track this component
  
  return (
    <>
      <UsageDashboard /> {/* Toggle overlay inside your dev app */}
      {/* Your app content */}
    </>
  );
}

📖 Usage Examples

Basic Component Tracking

import { useComponentUsage } from 'react-component-usage-visualizer';

function MyComponent({ title, count }) {
  useComponentUsage('MyComponent'); // Track renders and prop changes
  
  return <div>{title}: {count}</div>;
}

Advanced Hook Tracking

import { 
  useComponentUsage, 
  useEffectTracker, 
  useMemoTracker 
} from 'react-component-usage-visualizer';

function AdvancedComponent({ data, multiplier }) {
  useComponentUsage('AdvancedComponent');
  
  // Track specific hook usage
  useEffectTracker([data, multiplier]);
  useMemoTracker([data]);
  
  const expensiveValue = useMemo(() => {
    return data.reduce((acc, item) => acc + item.value * multiplier, 0);
  }, [data, multiplier]);
  
  return <div>Result: {expensiveValue}</div>;
}

Dashboard Integration

React.js

import { UsageDashboard } from 'react-component-usage-visualizer';

function App() {
  return (
    <div>
      <h1>My React App</h1>
      {/* Your components */}
      
      {/* Add the dashboard - shows floating button in dev mode */}
      <UsageDashboard />
    </div>
  );
}

React Native

import React from 'react';
import { View } from 'react-native';
import { UsageDashboard } from 'react-component-usage-visualizer';

function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your React Native components */}
      
      {/* Add the dashboard - shows floating button in dev mode */}
      <UsageDashboard />
    </View>
  );
}

🛠️ API Reference

Hooks

useComponentUsage(componentName)

Tracks component renders, prop changes, and provides analytics data.

Parameters:

• componentName (string): Name to identify the component in analytics

Returns:

• analytics: Object containing render count, prop changes, and timing data
• trackHookActivity: Function to manually track hook usage
• getUsageData: Function to get current usage data
• getHookActivity: Function to get hook activity data

useEffectTracker(dependencies)

Tracks useEffect hook usage with dependencies.

useMemoTracker(dependencies)

Tracks useMemo hook usage with dependencies.

useStateTracker()

Tracks useState hook usage.

Components

<UsageDashboard />

Renders the overlay analytics panel with:

• Overview tab: Performance metrics and component usage
• Heatmap tab: Visual render intensity heatmap
• Issues tab: Performance warnings and optimization suggestions
• Export functionality: Download data as JSON or CSV (web) / Share data (React Native)

Platform-specific behavior:

• React.js: Shows as floating overlay with file download
• React Native: Shows as modal with native sharing

Utilities

getGlobalUsageData()

Returns all collected usage data across all components.

clearUsageData()

Clears all collected usage data (useful for testing).

exportUsageData(data, format)

Exports usage data in specified format ('json' or 'csv').

Platform Utilities

getPlatform()

Returns the current platform: 'web', 'react-native', or 'unknown'.

isReactNative()

Returns true if running in React Native environment.

isWeb()

Returns true if running in web browser environment.

getExportMethod()

Returns the export method for the current platform: 'download' (web) or 'console' (React Native).

🎨 Dashboard Features

Overview Tab

• Total components tracked
• Total renders across all components
• Average renders per component
• Most/least rendered components
• Individual component render counts

Heatmap Tab

• Visual intensity map of component render frequency
• Color-coded bars showing render intensity
• Quick identification of performance hotspots

Issues Tab

• High render count warnings
• Inefficient render patterns
• Unused component detection
• Performance optimization suggestions

🔧 Advanced Configuration

Custom Analytics

import { getGlobalUsageData, exportUsageData } from 'react-component-usage-visualizer';

// Get all usage data
const allData = getGlobalUsageData();

// Export as JSON
const jsonData = exportUsageData(allData.components, 'json');

// Export as CSV
const csvData = exportUsageData(allData.components, 'csv');

Performance Monitoring

import { detectPerformanceIssues } from 'react-component-usage-visualizer';

// Check for performance issues
const issues = detectPerformanceIssues(usageData);
console.log('Performance issues:', issues);

🚨 Development Mode Only

This package is designed for development use only. The dashboard and tracking features should not be included in production builds. Consider using environment checks:

import { UsageDashboard } from 'react-component-usage-visualizer';

function App() {
  return (
    <div>
      {/* Your app */}
      {process.env.NODE_ENV === 'development' && <UsageDashboard />}
    </div>
  );
}

🤝 Contributing

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

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• NPM Package
• Issues

🙏 Acknowledgments

Inspired by React DevTools and the need for better component performance visualization in development environments.