react-runtime-tracer ⚡️

A zero-touch, dev-only runtime tracing library for large React applications.

Tracks component mounts, React Router navigations, and network calls (fetch/XHR) into a unified timeline — all accessible via a floating dev overlay.

Why?

Large React applications often suffer from "mystery renders" where a route change triggers a cascade of component mounts and network waterfalls. react-runtime-tracer helps you visualize the exact sequence of events in your app as they happen.

✅ Zero-touch: Wrap your root <App /> and you're done. No need to modify existing components. ✅ Dev-only: Completely disabled in production. Zero impact on your production bundle size or performance. ✅ Unified Timeline: See route changes, network requests, and component renders in exactly the order they occurred.

Installation

npm install react-runtime-tracer -D

(Or use yarn add -D, pnpm add -D)

Usage

Simply wrap your application root component.

import React from "react";
import ReactDOM from "react-dom/client";
import { RuntimeTracer } from "react-runtime-tracer";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <RuntimeTracer>
    <App />
  </RuntimeTracer>
);

The Dev Overlay

Press Ctrl + Shift + T to toggle the dev overlay panel in your browser.

The overlay features 3 tabs:

1. Timeline: A chronological list of all tracked events (renders, navigation, fetch calls).
2. Components: A grouped view of components by ID, showing total render time and mount/update counts.
3. Network: A list of all intercepted fetch and XMLHttpRequest calls, their HTTP methods, URLs, status codes, and durations.

Architecture

• Profiler Observer: Connects to the React <Profiler> API to passively measure render durations. Handles React 18 StrictMode double-render deduplication automatically.
• Router Observer: Monkey-patches history.pushState and history.replaceState and listens to popstate to track SPA navigations.
• Network Interceptor: Wraps window.fetch and XMLHttpRequest to log outgoing requests and associate them with the last committed React component.
• In-Memory Graph: A safe, capped rolling-buffer (max 500 events) that prevents memory leaks during long dev sessions.

⚠️ Dev-Only Note & Performance

This library makes use of the React <Profiler> API and network monkey-patching. It is strictly designed for development use.

By default, <RuntimeTracer> checks process.env.NODE_ENV !== "production". If it detects a production environment, it immediately returns <>{children}</> — ensuring no profiling logic, no network interception, and no UI rendering occurs in your production builds.

Local Testing

To test this library locally in another project:

1. Clone this repo & run npm install and npm run build
2. Run npm link in this directory
3. Go to your target React project and run npm link react-runtime-tracer

Roadmap

• [ ] Waterfall view for network requests
• [ ] Export traces to JSON
• [ ] Integration with specific state managers (Redux/Zustand)

License

MIT