vitest-react-profiler

React component render tracking and performance testing utilities for Vitest

📖 Documentation • 🚀 Quick Start • 📚 API Reference • 💬 Discussions

Features

• 🔍 Precise Render Tracking - Count exact number of renders with zero guesswork
• ⚡ Performance Monitoring - Detect unnecessary re-renders and track component behavior
• 🎯 Phase Detection - Distinguish between mount, update, and nested update phases
• 🪝 Hook Profiling - Profile custom hooks with full Context support via wrapper option
• ⏱️ Async Testing - Subscribe to renders with onRender() and wait with waitForNextRender()
• 🔔 Real-Time Notifications - React to renders immediately with event-based subscriptions
• ⚛️ React 18+ Concurrent Ready - Full support for useTransition and useDeferredValue
• 🧹 True Automatic Cleanup - Zero boilerplate! Components auto-clear between tests
• 🚀 Zero Config - Works out of the box with Vitest and React Testing Library
• 🛡️ Built-in Safety Mechanisms - Automatic detection of infinite render loops and memory leaks
• 💪 Full TypeScript Support - Complete type safety with custom Vitest matchers
• 🧬 Battle-Tested Quality - 100% mutation score, property-based testing, stress tests, SonarCloud verified
• 🔬 Mathematically Verified - 244 property tests with 130,000+ randomized scenarios per run
• 🏋️ Stress-Tested - 21 stress tests validate performance on 10,000-render histories
• 📊 Performance Baselines - 46 benchmarks establish regression detection metrics

👥 Who Is This For?

🎨 UI-Kit and Design System Developers

Building a UI-kit for your project or company? You need to track, measure, and improve component performance. This tool helps you:

• Catch unnecessary re-renders during development
• Set performance budgets for components
• Document performance characteristics in tests

📦 Open Source React Library Maintainers

Publishing React components? It's critical to prove your solution is optimized and won't degrade performance in user projects. With this tool, you can:

• Add performance tests to CI/CD pipelines
• Showcase performance metrics in documentation
• Track performance regressions between releases

🎯 Tech Leads and Staff Engineers

Making architectural decisions requires data, not assumptions. Use the tool to:

• Compare different state management approaches
• Evaluate architectural changes' performance impact
• Create performance guidelines for your team

📊 Teams with Strict Performance SLAs

Have strict performance requirements (fintech, healthcare, real-time systems)? The tool allows you to:

• Set thresholds for render counts
• Automatically verify SLA compliance in tests
• Track asynchronous state updates

Quick Start

Installation

npm install --save-dev vitest-react-profiler
# or
yarn add -D vitest-react-profiler
# or
pnpm add -D vitest-react-profiler

Setup

// vitest-setup.ts
import "vitest-react-profiler";

Configure Vitest:

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "jsdom",
    setupFiles: ["./vitest-setup.ts"],
  },
});

Your First Test

import { render } from '@testing-library/react';
import { withProfiler } from 'vitest-react-profiler';
import { MyComponent } from './MyComponent';

it('should render only once on mount', () => {
  const ProfiledComponent = withProfiler(MyComponent);
  render(<ProfiledComponent />);

  expect(ProfiledComponent).toHaveRenderedTimes(1);
  expect(ProfiledComponent).toHaveMountedOnce();
});

⚛️ React 18+ Concurrent Features

Full support for React 18+ Concurrent rendering features - no special configuration needed!

The library automatically tracks renders from:

useTransition / startTransition

Test components using transitions for non-urgent updates

useDeferredValue

Test components using deferred values for performance optimization

How It Works

The library uses React's built-in <Profiler> API, which automatically handles Concurrent mode:

• ✅ Transitions are tracked as regular renders
• ✅ Deferred values trigger additional renders (as expected)
• ✅ Interrupted renders are handled correctly by React
• ✅ No special configuration or setup required

Note: The library tracks renders, not React's internal scheduling. Concurrent Features work transparently - your tests verify component behavior, not React internals.

📚 Read the complete guide →

Documentation

📖 Full documentation is available in the Wiki

Quick Links

• Architecture Documentation - 📐 Complete technical architecture (15 sections, ~14,000 lines)
• Getting Started Guide - Installation and configuration
• API Reference - Complete API documentation
• Hook Profiling - Testing React hooks
• React 18+ Concurrent Features - useTransition & useDeferredValue
• Examples - Real-world usage patterns
• Best Practices - Tips and recommendations
• Troubleshooting - Common issues and solutions

Contributing

We welcome contributions! Please read our Contributing Guide and Code of Conduct.

# Run tests
npm test                    # Unit/integration tests (736 tests)
npm run test:properties     # Property-based tests (244 tests, 130k+ checks)
npm run test:stress         # Stress tests (21 tests, large histories)
npm run test:bench          # Performance benchmarks (46 benchmarks)
npm run test:mutation       # Mutation testing (100% score)

# Build
npm run build

License

MIT © Oleg Ivanov

Made with ❤️ by the community

Report Bug • Request Feature • Discussions