TracewayProvider

The TracewayProvider component initializes Traceway and provides context to child components.

Basic Usage

import { TracewayProvider } from "@tracewayapp/react";
 
function App() {
  return (
    <TracewayProvider connectionString="your-token@https://traceway.example.com/api/report">
      <YourApp />
    </TracewayProvider>
  );
}

Props

Prop	Type	Required	Description
`connectionString`	`string`	Yes	Your Traceway connection string
`options`	`object`	No	Configuration options
`children`	`ReactNode`	Yes	Child components

Options

Option	Type	Default	Description
`debug`	`boolean`	`false`	Log events to console
`debounceMs`	`number`	`1500`	Batch delay in milliseconds
`retryDelayMs`	`number`	`10000`	Retry delay for failed uploads
`version`	`string`	`undefined`	Your application version
`ignoreErrors`	`Array<string \| RegExp>`	`DEFAULT_IGNORE_PATTERNS`	Error patterns to ignore. Pass `[]` to capture all errors. See Error Filtering
`beforeCapture`	`(exception) => boolean`	`undefined`	Return `false` to suppress an error. See Error Filtering
`sessionRecording`	`boolean`	`true`	Enable the rrweb session recorder
`sessionRecordingSegmentDuration`	`number`	`30000`	rrweb segment length in ms
`recordAllSessions`	`boolean`	`false`	Always-on session recording. See Sessions
`captureLogs`	`boolean`	`true`	Mirror `console.*` calls into the rolling log buffer
`captureNetwork`	`boolean`	`true`	Record `fetch` / `XHR` calls as network actions
`captureNavigation`	`boolean`	`true`	Record History API push / replace / pop transitions
`eventsWindowMs`	`number`	`10000` (`30000` w/ `recordAllSessions`)	Rolling log/action buffer window
`eventsMaxCount`	`number`	`200` (`600` w/ `recordAllSessions`)	Hard cap on log/action buffer entries

Custom Attributes

Use <TracewayAttributes> or the useTracewayAttributes hook to bind a reactive map of attributes (userId, tenant, feature flags, etc.) to the SDK's global scope. The hook diffs against the previous map on every render and pushes only the deltas; on unmount, every key it currently owns is removed.

import { TracewayAttributes, useTracewayAttributes } from "@tracewayapp/react";
 
// As a component:
<TracewayAttributes attributes={user ? { userId: user.id, tenant: org.id } : null} />
 
// Or as a hook:
function App() {
  useTracewayAttributes({ userId: user?.id, tenant: org?.id });
  return <Routes />;
}

Both accept null / undefined as "empty map" — useful while user data loads or after logout. New object reference with the same content does not trigger SDK calls.

For imperative use (background workers, init scripts), the same primitives are exported as plain functions:

import { setAttribute, setAttributes, removeAttribute, clearAttributes } from "@tracewayapp/react";
 
setAttribute("build_channel", import.meta.env.VITE_CHANNEL ?? "dev");
setAttributes({ tenant: "acme", plan: "pro" });
clearAttributes(); // on logout

Layering on each event: defaults < global scope < per-call. See Sessions for the full attribute model.

Example with Options

<TracewayProvider
  connectionString="your-token@https://traceway.example.com/api/report"
  options={{
    debug: process.env.NODE_ENV === "development",
    version: process.env.REACT_APP_VERSION,
    debounceMs: 1000,
  }}
>
  <YourApp />
</TracewayProvider>

Capture All Errors

By default, 4xx HTTP errors, network errors, and timeouts are ignored. To capture everything:

<TracewayProvider
  connectionString="your-token@https://traceway.example.com/api/report"
  options={{ ignoreErrors: [] }}
>
  <YourApp />
</TracewayProvider>

Environment-Specific Setup

function App() {
  const connectionString = process.env.NODE_ENV === "production"
    ? process.env.REACT_APP_TRACEWAY_PROD
    : process.env.REACT_APP_TRACEWAY_DEV;
 
  return (
    <TracewayProvider connectionString={connectionString}>
      <YourApp />
    </TracewayProvider>
  );
}

Placement

Place TracewayProvider as high as possible in your component tree, typically in your root App component or index.js:

// index.js
import React from "react";
import ReactDOM from "react-dom/client";
import { TracewayProvider } from "@tracewayapp/react";
import App from "./App";
 
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <React.StrictMode>
    <TracewayProvider connectionString="your-token@...">
      <App />
    </TracewayProvider>
  </React.StrictMode>
);

TracewayContext

For advanced use cases, you can access the context directly:

import { TracewayContext } from "@tracewayapp/react";
import { useContext } from "react";
 
function MyComponent() {
  const traceway = useContext(TracewayContext);
  // Use traceway.captureException, etc.
}

However, the useTraceway hook is preferred for most use cases.

Quick Start Error Boundary