Connects React's lifecycle, your network requests, and unhandled errors into a single, comprehensive timeline — with a beautiful floating DevTools overlay.

📥 Installation

npm install @traceora/react @traceora/core

Tip: Also install @traceora/vite-plugin to instrument named function components with block bodies.

✨ Exports

| Export | Type | Description | |---|---|---| | <TraceoraProvider> | Component | Initializes the core engine, instruments fetch/XHR/History API, catches errors, shares the EventEmitter via React Context. | | <TraceoraErrorBoundary> | Component | Intercepts React render crashes → logs them to the timeline → shows a fallback UI. | | <TraceoraDevtools /> | Component | Floating, real-time visual timeline for development. Drop it in and go. | | useTrace() | Hook | Start an interaction trace. Its fetch() method propagates the trace ID to a request. | | useComponentTrace() | Hook | Tracks component mount & render. The Vite plugin injects it into supported named function components. |

🔧 Usage

1. Wrap your application

import {
  TraceoraProvider,
  TraceoraErrorBoundary,
  TraceoraDevtools,
} from '@traceora/react';

function App() {
  return (
    <TraceoraProvider>
      <TraceoraErrorBoundary>
        <YourApp />
        <TraceoraDevtools /> {/* Floating timeline overlay */}
      </TraceoraErrorBoundary>
    </TraceoraProvider>
  );
}

2. Trace interactions manually

import { useTrace } from '@traceora/react';

export function UserProfile() {
  const startTrace = useTrace();

  const handleSave = () => {
    // Links this click + any subsequent API calls under one Trace ID
    const trace = startTrace('Save_Profile');

    // Use the trace handle to correlate this request with the interaction.
    void trace.fetch('/api/save', { method: 'POST' });
  };

  return <button onClick={handleSave}>Save</button>;
}

Instrumentation is enabled in development by default. Set config={{ enabled: true }} to opt in elsewhere. Event history is capped at 1,000 by default. Request bodies and headers are excluded unless captureRequestBodies or captureRequestHeaders is enabled; inspect captured data carefully before enabling either option.

🔗 Related Packages

| Package | Role | |---|---| | @traceora/core | The underlying event engine | | @traceora/vite-plugin | Build-time instrumentation for supported named function components | | @traceora/next | Next.js-specific integration |