Skip to content

The only tool you need to know what is happening and how to fix it.

updated docs for the upgraded react api and documenting the nextjs instalation steps

ddux7d49cb483d0c
diff --git a/docs/pages/client/jquery/index.mdx b/docs/pages/client/jquery/index.mdx
index fcf04d6c..b9c612d7 100644
--- a/docs/pages/client/jquery/index.mdx
+++ b/docs/pages/client/jquery/index.mdx
@@ -16,6 +16,8 @@ import { init } from "@tracewayapp/jquery";
init("your-token@https://cloud.tracewayapp.com/api/report");
```
+Session recording is on by default — the last ~30s of DOM events ship with every captured exception.
+
### Via CDN
No build step needed — add two script tags after jQuery:
diff --git a/docs/pages/client/js-sdk/exceptions.mdx b/docs/pages/client/js-sdk/exceptions.mdx
index adbd1f61..c9b7df33 100644
--- a/docs/pages/client/js-sdk/exceptions.mdx
+++ b/docs/pages/client/js-sdk/exceptions.mdx
@@ -86,4 +86,4 @@ For best stack traces, always throw and catch actual `Error` objects.
## React Error Boundaries
-For React applications, use the `@tracewayapp/react` package which provides a `TracewayErrorBoundary` component that automatically captures React component errors. See the [React documentation](/client/react/error-boundary) for details.
+For React applications, use the `@tracewayapp/react` package. Its `<TracewayProvider>` itself acts as an error boundary — render-time exceptions are captured automatically and re-thrown so the app behaves exactly as without Traceway. See the [React documentation](/client/react) for setup, or the [Error Boundary page](/client/react/error-boundary) if you need a custom fallback UI for a specific subtree.
diff --git a/docs/pages/client/nextjs/_meta.json b/docs/pages/client/nextjs/_meta.json
index 13ec779a..8393d864 100644
--- a/docs/pages/client/nextjs/_meta.json
+++ b/docs/pages/client/nextjs/_meta.json
@@ -1,4 +1,3 @@
{
- "index": "Quick Start",
- "traces": "Traces"
+ "index": "Quick Start"
}
diff --git a/docs/pages/client/nextjs/index.mdx b/docs/pages/client/nextjs/index.mdx
index 1669918a..fce752cf 100644
--- a/docs/pages/client/nextjs/index.mdx
+++ b/docs/pages/client/nextjs/index.mdx
@@ -1,59 +1,204 @@
-# Next.js (OpenTelemetry)
+# Next.js
-Instrument your Next.js application with OpenTelemetry and export server-side traces and metrics to Traceway. This guide covers the App Router (Next.js 13.4+). For client-side error tracking, see `@tracewayapp/next` on the Connection page in your Traceway dashboard.
+Traceway instruments Next.js on two sides:
-## Installation
+- **Frontend (Browser)** — uncaught errors, render errors, and session recording via [`@tracewayapp/react`](https://www.npmjs.com/package/@tracewayapp/react).
+- **Backend (Server)** — request traces, database spans, and server-side exceptions via OpenTelemetry.
+
+The two work side by side on the same project. Most apps will want both.
+
+---
+
+## Quick Start
+
+Minimum configuration to get errors flowing in. Drop these in, replace the connection string, and you're done.
+
+**Frontend** — install `@tracewayapp/react`, wrap your app in `TracewayProvider`:
+
+```bash
+npm install @tracewayapp/react
+```
+
+```tsx
+// app/traceway-provider.tsx
+"use client";
+
+import { TracewayProvider } from "@tracewayapp/react";
+
+export function TracewayClientProvider({ children }: { children: React.ReactNode }) {
+ return (
+ <TracewayProvider connectionString="your-token@https://traceway.example.com/api/report">
+ {children}
+ </TracewayProvider>
+ );
+}
+```
+
+```tsx
+// app/layout.tsx
+import { TracewayClientProvider } from "./traceway-provider";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+ return (
+ <html lang="en">
+ <body>
+ <TracewayClientProvider>{children}</TracewayClientProvider>
+ </body>
+ </html>
+ );
+}
+```
+
+**Backend** — install the OTel Node SDK and add a single `instrumentation.ts`:
```bash
npm install @opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http \
- @opentelemetry/exporter-metrics-otlp-http \
@opentelemetry/api
```
-If you use Prisma, also install its OTel instrumentation for automatic query tracing:
+```typescript
+// instrumentation.ts (project root)
+export async function register() {
+ if (process.env.NEXT_RUNTIME === "nodejs") {
+ const { NodeSDK } = await import("@opentelemetry/sdk-node");
+ const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+ const { getNodeAutoInstrumentations } = await import("@opentelemetry/auto-instrumentations-node");
+ const { Resource } = await import("@opentelemetry/resources");
-```bash
-npm install @prisma/instrumentation
+ new NodeSDK({
+ resource: new Resource({ "service.name": "my-nextjs-app" }),
+ traceExporter: new OTLPTraceExporter({
+ url: "https://your-traceway-instance.com/api/otel/v1/traces",
+ headers: { Authorization: "Bearer your-project-token" },
+ }),
+ instrumentations: [getNodeAutoInstrumentations()],
+ }).start();
+ }
+}
```
-## Setup
+> Next.js < 15: also set `experimental.instrumentationHook: true` in `next.config.js`. Not needed for 15+.
+
+That's the whole base setup. The rest of this page is for the cases where the defaults aren't enough.
+
+---
+
+## Frontend (Browser)
+
+Captures browser errors, render errors, and session recordings. Works with both App Router and Pages Router.
+
+### Pages Router setup
+
+If you're still on `pages/`, mount the provider directly in `_app.tsx`:
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from "next/app";
+import { TracewayProvider } from "@tracewayapp/react";
+
+export default function App({ Component, pageProps }: AppProps) {
+ return (
+ <TracewayProvider connectionString="your-token@https://traceway.example.com/api/report">
+ <Component {...pageProps} />
+ </TracewayProvider>
+ );
+}
+```
+
+### What you get by default
+
+Defaults match the rest of the JS SDK family — no flags needed:
+
+| Option | Default | Purpose |
+|---|---|---|
+| `sessionRecording` | `true` | rrweb recorder runs; segments ride along with each exception |
+| `recordAllSessions` | `false` | Only exception-bound clips upload (no always-on recording) |
+| `captureLogs` | `true` | `console.{log,info,warn,error}` mirrored into the rolling buffer |
+| `captureNetwork` | `true` | `fetch` and XHR calls recorded as network actions |
+| `captureNavigation` | `true` | History API push/replace/pop recorded as navigation actions |
+
+The `connectionString` uses the standard `{token}@{apiUrl}` format from your Traceway project page.
+
+`TracewayProvider` also acts as a React error boundary — render-time exceptions are captured and re-thrown so your app behaves exactly as without Traceway. No separate `<TracewayErrorBoundary>` is required.
+
+### Capture errors manually
+
+Inside any client component, use the `useTraceway` hook:
+
+```tsx
+"use client";
+
+import { useTraceway } from "@tracewayapp/react";
+
+export function CheckoutButton() {
+ const { captureException } = useTraceway();
+
+ async function handleClick() {
+ try {
+ await placeOrder();
+ } catch (e) {
+ captureException(e as Error);
+ }
+ }
+
+ return <button onClick={handleClick}>Place order</button>;
+}
+```
+
+### Test the frontend integration
+
+Drop a throw into any client component and reload:
+
+```tsx
+"use client";
+
+export function TestErrorButton() {
+ return (
+ <button onClick={() => { throw new Error("Test error from Next.js client"); }}>
+ Send test error
+ </button>
+ );
+}
+```
+
+The error should appear in your Traceway dashboard under **Issues** within a few seconds, with the session recording attached.
+
+---
+
+## Backend (Server)
-Create an `instrumentation.ts` file in the root of your project (next to `next.config.js`). Next.js loads this file automatically during server startup — no `--require` flag needed.
+Captures server-side traces, database spans, and exceptions thrown in Server Components, route handlers, and `getServerSideProps` — none of which the frontend SDK can see.
+
+### Setup with Prisma + metrics
+
+The Quick Start above is the minimum. If you use Prisma or want metric export too, the fuller `instrumentation.ts` looks like:
+
+```bash
+npm install @prisma/instrumentation @opentelemetry/exporter-metrics-otlp-http
+```
```typescript
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
const { NodeSDK } = await import("@opentelemetry/sdk-node");
- const { OTLPTraceExporter } = await import(
- "@opentelemetry/exporter-trace-otlp-http"
- );
- const { OTLPMetricExporter } = await import(
- "@opentelemetry/exporter-metrics-otlp-http"
- );
- const { PeriodicExportingMetricReader } = await import(
- "@opentelemetry/sdk-metrics"
- );
- const { getNodeAutoInstrumentations } = await import(
- "@opentelemetry/auto-instrumentations-node"
- );
+ const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+ const { OTLPMetricExporter } = await import("@opentelemetry/exporter-metrics-otlp-http");
+ const { PeriodicExportingMetricReader } = await import("@opentelemetry/sdk-metrics");
+ const { getNodeAutoInstrumentations } = await import("@opentelemetry/auto-instrumentations-node");
const { Resource } = await import("@opentelemetry/resources");
- const { PrismaInstrumentation } = await import(
- "@prisma/instrumentation"
- );
+ const { PrismaInstrumentation } = await import("@prisma/instrumentation");
- const sdk = new NodeSDK({
+ new NodeSDK({
resource: new Resource({
"service.name": "my-nextjs-app",
"service.version": "1.0.0",
}),
-
traceExporter: new OTLPTraceExporter({
url: "https://your-traceway-instance.com/api/otel/v1/traces",
headers: { Authorization: "Bearer your-project-token" },
}),
-
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: "https://your-traceway-instance.com/api/otel/v1/metrics",
@@ -61,23 +206,18 @@ export async function register() {
}),
exportIntervalMillis: 30_000,
}),
-
instrumentations: [
getNodeAutoInstrumentations(),
new PrismaInstrumentation(),
],
- });
-
- sdk.start();
+ }).start();
}
}
```
-> If you don't use Prisma, remove the `PrismaInstrumentation` import and the `new PrismaInstrumentation()` line.
-
-The `process.env.NEXT_RUNTIME === "nodejs"` guard is required — Next.js runs `instrumentation.ts` in both the Node.js and Edge runtimes, but the OTel Node SDK only works in Node.js. Dynamic `import()` prevents OTel packages from being bundled into the Edge runtime.
+The `process.env.NEXT_RUNTIME === "nodejs"` guard is required — Next.js runs `instrumentation.ts` in both the Node.js and Edge runtimes, but the OTel Node SDK only works in Node.js. Dynamic `import()` keeps OTel out of the Edge bundle.
-## Enabling the Instrumentation Hook (Next.js 13.4–14.x)
+### Enabling the Instrumentation Hook (Next.js 13.4–14.x)
For Next.js versions before 15, enable the instrumentation hook in `next.config.js`:
@@ -92,11 +232,11 @@ const nextConfig = {
module.exports = nextConfig;
```
-This is not needed for Next.js 15+, where the instrumentation hook is stable by default.
+Not needed for Next.js 15+, where the hook is stable by default.
-## Route Helper (Required)
+### Route Helper (Required)
-Next.js (App Router) does not use Express or Fastify under the hood, so the OTel auto-instrumentation cannot set `http.route` automatically. Without it, Traceway falls back to the literal URL path — every unique URL becomes a separate endpoint (e.g., `/api/users/1` and `/api/users/2` instead of `GET /api/users/[id]`).
+Next.js (App Router) doesn't use Express or Fastify under the hood, so OTel auto-instrumentation can't set `http.route` automatically. Without it, Traceway falls back to the literal URL path — every `/api/users/1`, `/api/users/2` becomes a separate endpoint instead of grouping under `GET /api/users/[id]`.
Create a `withRoute` helper that wraps your API route handlers. It sets `http.route` for endpoint grouping and records exceptions as Issues:
@@ -159,7 +299,7 @@ export const GET = withRoute("/api/users/[id]", async (req, { params }) => {
});
```
-## What Gets Captured
+### What gets captured
With the setup above, OTel captures the following automatically:
@@ -174,46 +314,165 @@ With the setup above, OTel captures the following automatically:
Root SERVER spans become **Endpoints** in Traceway (e.g., `GET /api/users/[id]`), child spans become **Spans**, and exception events become **Issues**.
-### Prisma Auto-Instrumentation
+#### Prisma auto-instrumentation
-With `@prisma/instrumentation` registered in the SDK, every Prisma query automatically creates child spans — no manual wrapping needed:
+With `@prisma/instrumentation` registered, every Prisma query creates child spans — no manual wrapping needed:
```typescript
-// Just use Prisma normally — spans are created automatically
const users = await prisma.user.findMany();
const user = await prisma.user.create({ data: { name, email } });
```
-The resulting trace in Traceway:
+Resulting trace:
```
GET /api/users ← Endpoint
└─ prisma:client:query ← Span (findMany on User)
```
-### Outgoing fetch() Auto-Instrumentation
+#### Outgoing fetch() auto-instrumentation
-Outgoing `fetch()` calls are automatically traced by `@opentelemetry/instrumentation-undici`:
+Outgoing `fetch()` calls are traced by `@opentelemetry/instrumentation-undici`:
```typescript
export const GET = withRoute("/api/external", async () => {
- // This fetch automatically creates a child span
const res = await fetch("https://api.example.com/data");
const data = await res.json();
return Response.json(data);
});
```
-The resulting trace in Traceway:
+Resulting trace:
```
GET /api/external ← Endpoint
└─ GET ← Span (https://api.example.com/data)
```
-## Environment Variable Alternative
+### Manual spans
+
+For operations that aren't auto-instrumented (SQLite via `better-sqlite3`, Server Component rendering, custom business logic), open a span by hand with `@opentelemetry/api`:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { withRoute } from "@/lib/with-route";
+
+const tracer = trace.getTracer("my-nextjs-app");
+
+export const GET = withRoute("/api/orders/[id]", async (req, { params }) => {
+ const { id } = await params;
+
+ return tracer.startActiveSpan("fetch-order", async (span) => {
+ try {
+ span.setAttribute("order.id", id);
+ const order = await db.orders.findById(id);
+
+ if (!order) {
+ span.setStatus({ code: SpanStatusCode.ERROR, message: "Order not found" });
+ span.end();
+ return Response.json({ error: "Not found" }, { status: 404 });
+ }
+
+ span.end();
+ return Response.json(order);
+ } catch (error) {
+ span.recordException(error as Error);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
+ span.end();
+ throw error;
+ }
+ });
+});
+```
+
+#### Server Components
+
+Wrap Server Component bodies in a span to see their render time in the trace:
+
+```typescript
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-nextjs-app");
+
+export default async function UsersPage() {
+ return tracer.startActiveSpan("UsersPage.render", async (span) => {
+ try {
+ const users = await fetchUsers();
+ span.setAttribute("user.count", users.length);
+ return (
+ <ul>
+ {users.map((user) => (<li key={user.id}>{user.name}</li>))}
+ </ul>
+ );
+ } finally {
+ span.end();
+ }
+ });
+}
+```
+
+Server Component spans appear as **Spans** in Traceway, nested under the parent HTTP request trace.
+
+#### Nested spans
+
+Spans created inside an active span are automatically linked as children:
+
+```typescript
+async function processPayment(orderId: string) {
+ return tracer.startActiveSpan("process-payment", async (span) => {
+ try {
+ await validateCard(orderId);
+ await chargeAmount(orderId);
+ span.setStatus({ code: SpanStatusCode.OK });
+ } catch (error) {
+ span.recordException(error as Error);
+ span.setStatus({ code: SpanStatusCode.ERROR });
+ throw error;
+ } finally {
+ span.end();
+ }
+ });
+}
+```
+
+#### Recording an exception without re-throwing
+
+`withRoute` already records errors that bubble up. If you catch an error and want to log it on the active span without throwing:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+export const POST = withRoute("/api/checkout", async () => {
+ const span = trace.getActiveSpan();
+ try {
+ await processPayment();
+ } catch (error) {
+ if (span) {
+ span.recordException(error as Error);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
+ }
+ return Response.json({ error: "Payment failed" }, { status: 500 });
+ }
+ return Response.json({ status: "ok" });
+});
+```
+
+### Auto vs manual reference
+
+| Operation | Auto-instrumented? | Notes |
+|-----------|-------------------|-------|
+| HTTP requests (incoming) | Partial | `withRoute` sets `http.route` + catches exceptions |
+| Outgoing `fetch()` calls | Yes | Via `instrumentation-undici` |
+| Prisma queries | Yes | Via `@prisma/instrumentation` |
+| Database queries (`pg`, `mysql2`, `mongodb`) | Yes | CJS packages — patched by `require-in-the-middle` |
+| Cache (`redis`, `ioredis`) | Yes | CJS packages — patched automatically |
+| SQLite (`better-sqlite3`) | No | Use manual spans |
+| Server Component rendering | No | Use `tracer.startActiveSpan()` |
+| Custom business logic | No | Use `tracer.startActiveSpan()` |
-Instead of hardcoding the endpoint and token, you can use standard OTel environment variables:
+### Environment variable alternative
+
+Instead of hardcoding the endpoint and token, use standard OTel environment variables:
```bash
export OTEL_SERVICE_NAME="my-nextjs-app"
@@ -221,9 +480,9 @@ export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-traceway-instance.com/api/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-project-token"
```
-With these set, the SDK picks them up automatically — your `instrumentation.ts` can omit the exporter URLs and headers.
+With these set, your `instrumentation.ts` can omit the exporter URLs and headers — the SDK picks them up automatically.
-## Test Your Integration
+### Test the backend integration
Add a test API route:
@@ -232,15 +491,18 @@ Add a test API route:
import { withRoute } from "@/lib/with-route";
export const GET = withRoute("/api/test-error", async () => {
- throw new Error("Test error from Next.js");
+ throw new Error("Test error from Next.js server");
});
```
Visit `/api/test-error` and check your Traceway dashboard — the error should appear under **Issues** with a full stack trace, and the endpoint should be grouped as `GET /api/test-error`.
+---
+
## Next Steps
-- [Traces](/client/nextjs/traces) — manual spans, Server Component tracing
+- [React SDK Reference](/client/react) — provider options, hooks, advanced usage
+- [Sessions](/learn/sessions) — how session recording is stored and replayed
- [Node.js OTel Guide](/client/node-sdk) — general Node.js setup details
- [OTel Overview](/client/otel) — protocol details and authentication
- [OTel Trace Mapping](/client/otel/traces) — how OTel spans map to Traceway concepts
diff --git a/docs/pages/client/nextjs/traces.mdx b/docs/pages/client/nextjs/traces.mdx
deleted file mode 100644
index f219d4c1..00000000
--- a/docs/pages/client/nextjs/traces.mdx
+++ /dev/null
@@ -1,135 +0,0 @@
-# Traces
-
-Prisma queries and outgoing `fetch()` calls are auto-instrumented. This page covers manual span creation for operations that aren't covered by auto-instrumentation.
-
-## Manual Spans
-
-Use `@opentelemetry/api` to create custom spans for operations that aren't auto-instrumented:
-
-```typescript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-import { withRoute } from "@/lib/with-route";
-
-const tracer = trace.getTracer("my-nextjs-app");
-
-export const GET = withRoute("/api/orders/[id]", async (req, { params }) => {
- const { id } = await params;
-
- return tracer.startActiveSpan("fetch-order", async (span) => {
- try {
- span.setAttribute("order.id", id);
- const order = await db.orders.findById(id);
-
- if (!order) {
- span.setStatus({ code: SpanStatusCode.ERROR, message: "Order not found" });
- span.end();
- return Response.json({ error: "Not found" }, { status: 404 });
- }
-
- span.end();
- return Response.json(order);
- } catch (error) {
- span.recordException(error as Error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
- span.end();
- throw error;
- }
- });
-});
-```
-
-## Server Components
-
-Add tracing to React Server Components:
-
-```typescript
-import { trace } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-nextjs-app");
-
-export default async function UsersPage() {
- return tracer.startActiveSpan("UsersPage.render", async (span) => {
- try {
- const users = await fetchUsers();
- span.setAttribute("user.count", users.length);
-
- return (
- <ul>
- {users.map((user) => (
- <li key={user.id}>{user.name}</li>
- ))}
- </ul>
- );
- } finally {
- span.end();
- }
- });
-}
-```
-
-Server Component spans appear as **Spans** in Traceway, nested under the parent HTTP request trace.
-
-## Exception Recording
-
-The `withRoute` helper automatically records thrown errors. For cases where you catch an error and want to record it without re-throwing:
-
-```typescript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
-app.get("/api/checkout", async (c) => {
- const span = trace.getActiveSpan();
- try {
- await processPayment();
- } catch (error) {
- if (span) {
- span.recordException(error as Error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
- }
- return Response.json({ error: "Payment failed" }, { status: 500 });
- }
- return Response.json({ status: "ok" });
-});
-```
-
-## Nested Spans
-
-Spans created inside an active span are automatically linked as children:
-
-```typescript
-const tracer = trace.getTracer("my-nextjs-app");
-
-async function processPayment(orderId: string) {
- return tracer.startActiveSpan("process-payment", async (span) => {
- try {
- await validateCard(orderId);
- await chargeAmount(orderId);
- span.setStatus({ code: SpanStatusCode.OK });
- } catch (error) {
- span.recordException(error as Error);
- span.setStatus({ code: SpanStatusCode.ERROR });
- throw error;
- } finally {
- span.end();
- }
- });
-}
-```
-
-## What Gets Auto-Instrumented vs Manual
-
-| Operation | Auto-Instrumented? | Notes |
-|-----------|-------------------|-------|
-| HTTP requests (incoming) | Partial | `withRoute` sets `http.route` + catches exceptions |
-| Outgoing `fetch()` calls | Yes | Via `instrumentation-undici` |
-| Prisma queries | Yes | Via `@prisma/instrumentation` |
-| Database queries (`pg`, `mysql2`, `mongodb`) | Yes | CJS packages — patched by `require-in-the-middle` |
-| Cache (`redis`, `ioredis`) | Yes | CJS packages — patched automatically |
-| SQLite (`better-sqlite3`) | No | Use manual spans |
-| Server Component rendering | No | Use `tracer.startActiveSpan()` |
-| Custom business logic | No | Use `tracer.startActiveSpan()` |
-
-## Next Steps
-
-- [Quick Start](/client/nextjs) — setup and installation
-- [Node.js Traces](/client/node-sdk/traces) — more on manual spans and context propagation
-- [Node.js Metrics](/client/node-sdk/metrics) — custom metrics with OTel
diff --git a/docs/pages/client/react-native/index.mdx b/docs/pages/client/react-native/index.mdx
index e8107a1d..39ce9cb7 100644
--- a/docs/pages/client/react-native/index.mdx
+++ b/docs/pages/client/react-native/index.mdx
@@ -10,26 +10,21 @@ npm install @tracewayapp/react-native
## Setup
-Wrap your app in `TracewayProvider` from your entry component (typically `App.tsx`). Mounting the provider runs `init(...)` once, which installs RN's `ErrorUtils` global handler, the `fetch` / `XMLHttpRequest` wrappers, and the `console.*` mirror:
+Wrap your app in `TracewayProvider` from your entry component (typically `App.tsx`). Mounting the provider runs `init(...)` once, which installs RN's `ErrorUtils` global handler, the `fetch` / `XMLHttpRequest` wrappers, and the `console.*` mirror. The provider also catches render-time errors anywhere below it and reports them automatically — no separate error boundary needed:
```tsx
-import { TracewayProvider, TracewayErrorBoundary } from "@tracewayapp/react-native";
+import { TracewayProvider } from "@tracewayapp/react-native";
export default function App() {
return (
- <TracewayProvider
- connectionString="your-token@https://traceway.example.com/api/report"
- options={{ version: "1.0.0" }}
- >
- <TracewayErrorBoundary fallback={<CrashScreen />}>
- <RootNavigator />
- </TracewayErrorBoundary>
+ <TracewayProvider connectionString="your-token@https://traceway.example.com/api/report">
+ <RootNavigator />
</TracewayProvider>
);
}
```
-That's it. Every uncaught throw, unhandled promise rejection, render-time error inside `<TracewayErrorBoundary>`, and `fetch` call is captured automatically.
+That's it. Every uncaught throw, unhandled promise rejection, render-time exception, and `fetch` call is captured automatically. If you want to replace a crashed subtree with a custom fallback view, `TracewayErrorBoundary` is still exported for that purpose.
> **No screen recording.** Unlike the browser SDK ([`@tracewayapp/frontend`](/client/js-sdk?sdk=js-generic)), this package does not record the screen. The `rrweb` recorder is intentionally absent — nothing in the bundle reaches into a DOM that doesn't exist.
@@ -255,7 +250,7 @@ For each captured exception: `device info < global scope < per-call`.
- **Uncaught throws** on the JS thread via `ErrorUtils.setGlobalHandler` — RN's equivalent of `window.onerror`. The red-box dev overlay still appears; we forward to the previous handler.
- **Unhandled promise rejections** — `Promise.reject(...)` without a `.catch()` reaches the same `ErrorUtils` handler.
-- **Render errors** — when wrapped in `<TracewayErrorBoundary>`, exceptions thrown during render or in lifecycle methods are captured.
+- **Render errors** — `<TracewayProvider>` itself acts as an error boundary: exceptions thrown during render or in lifecycle methods are captured and re-thrown so your app behaves exactly as without Traceway.
- **`fetch` calls** — wrapped at `init()`, recorded with method, URL, status, duration, byte counts.
- **`XMLHttpRequest` calls** — RN polyfills XHR (and `fetch` is implemented on top of it on some platforms); both paths are covered.
- **Console output** — `console.{debug,log,info,warn,error}` is mirrored into the log buffer that rides along the next exception.
diff --git a/docs/pages/client/react/error-boundary.mdx b/docs/pages/client/react/error-boundary.mdx
index 7ea2007f..07ec2e44 100644
--- a/docs/pages/client/react/error-boundary.mdx
+++ b/docs/pages/client/react/error-boundary.mdx
@@ -1,6 +1,8 @@
# Error Boundary
-The `TracewayErrorBoundary` component catches React errors and reports them to Traceway.
+> **Deprecated since v1.1.0.** `TracewayProvider` now catches render errors and reports them on its own. Use `TracewayErrorBoundary` only when you need a custom `fallback` UI for a specific subtree. This component will be removed in v2.
+
+The `TracewayErrorBoundary` component catches React errors in a subtree, reports them to Traceway, and renders a `fallback` in place of the crashed UI.
## Basic Usage
diff --git a/docs/pages/client/react/index.mdx b/docs/pages/client/react/index.mdx
index e51af88a..0599db12 100644
--- a/docs/pages/client/react/index.mdx
+++ b/docs/pages/client/react/index.mdx
@@ -10,7 +10,7 @@ npm install @tracewayapp/react
## Setup
-Wrap your application with `TracewayProvider`:
+Wrap your application with `TracewayProvider`. It also acts as an error boundary — render-time exceptions thrown anywhere in the tree are captured and reported automatically, then re-thrown so your app behaves exactly as it would without Traceway installed. Session recording is on by default; the last ~30s of DOM events ship with every captured exception:
```jsx
import { TracewayProvider } from "@tracewayapp/react";
@@ -26,23 +26,7 @@ function App() {
export default App;
```
-## Add Error Boundary
-
-Wrap components that might throw errors:
-
-```jsx
-import { TracewayProvider, TracewayErrorBoundary } from "@tracewayapp/react";
-
-function App() {
- return (
- <TracewayProvider connectionString="your-token@https://traceway.example.com/api/report">
- <TracewayErrorBoundary fallback={<ErrorPage />}>
- <YourApp />
- </TracewayErrorBoundary>
- </TracewayProvider>
- );
-}
-```
+> **Custom fallback UI?** If you want to replace a crashed subtree with a fallback view instead of letting the error propagate, wrap the relevant section in `TracewayErrorBoundary` — it's still exported for that purpose, but is no longer required for capture.
## Capture Errors Manually
diff --git a/docs/pages/client/svelte/index.mdx b/docs/pages/client/svelte/index.mdx
index f1e8231e..7a353170 100644
--- a/docs/pages/client/svelte/index.mdx
+++ b/docs/pages/client/svelte/index.mdx
@@ -10,20 +10,26 @@ npm install @tracewayapp/svelte
## Setup
-Call `setupTraceway` in your root component (e.g., `+layout.svelte` for SvelteKit):
+Call `setupTraceway` in your root layout. The `if (browser)` guard keeps the rrweb recorder out of the SSR bundle. Session recording is on by default — the last ~30s of DOM events ship with every captured exception:
```svelte
+<!-- src/routes/+layout.svelte -->
<script>
import { setupTraceway } from "@tracewayapp/svelte";
+ import { browser } from "$app/environment";
- setupTraceway({
- connectionString: "your-token@https://traceway.example.com/api/report",
- });
+ if (browser) {
+ setupTraceway({
+ connectionString: "your-token@https://traceway.example.com/api/report",
+ });
+ }
</script>
<slot />
```
+For a non-SvelteKit Svelte app, drop the `if (browser)` guard and import nothing from `$app/environment`.
+
## Capture Errors in Components
Use `getTraceway` in child components:
@@ -82,27 +88,6 @@ Use `getTraceway` in child components:
Click the button and check your Traceway dashboard to verify the error appears.
-## SvelteKit Setup
-
-For SvelteKit, set up Traceway in your root layout:
-
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
- import { setupTraceway } from "@tracewayapp/svelte";
- import { browser } from "$app/environment";
-
- // Only initialize on client
- if (browser) {
- setupTraceway({
- connectionString: "your-token@https://traceway.example.com/api/report",
- });
- }
-</script>
-
-<slot />
-```
-
## Distributed Tracing
The SDK automatically instruments `fetch` to propagate a `traceway-trace-id` header on same-origin requests. This links frontend errors to the backend requests that caused them — no extra configuration needed.
diff --git a/docs/pages/client/vue/index.mdx b/docs/pages/client/vue/index.mdx
index a391c3f4..6d10767f 100644
--- a/docs/pages/client/vue/index.mdx
+++ b/docs/pages/client/vue/index.mdx
@@ -10,7 +10,7 @@ npm install @tracewayapp/vue
## Setup
-Install the Traceway plugin in your Vue application:
+Install the Traceway plugin in your Vue application. Session recording is on by default — the last ~30s of DOM events ship with every captured exception:
```javascript
import { createApp } from "vue";
diff --git a/frontend/src/lib/utils/framework-code.ts b/frontend/src/lib/utils/framework-code.ts
index 82853499..87f05bcc 100644
--- a/frontend/src/lib/utils/framework-code.ts
+++ b/frontend/src/lib/utils/framework-code.ts
@@ -21,7 +21,7 @@ export function getInstallCommand(framework: Framework): string {
case 'vuejs':
return 'npm install @tracewayapp/vue';
case 'nextjs':
- return 'npm install @tracewayapp/next';
+ return 'npm install @tracewayapp/react';
case 'nestjs':
return 'npm install @tracewayapp/nest';
case 'express':
@@ -153,12 +153,16 @@ function App() {
export default App;`;
case 'svelte':
- return `<script>
+ return `<!-- src/routes/+layout.svelte -->
+<script>
import { setupTraceway } from "@tracewayapp/svelte";
+ import { browser } from "$app/environment";
- setupTraceway({
- connectionString: "${connectionString}",
- });
+ if (browser) {
+ setupTraceway({
+ connectionString: "${connectionString}",
+ });
+ }
</script>
<slot />`;
@@ -177,11 +181,31 @@ app.use(createTracewayPlugin({
app.mount("#app");`;
case 'nextjs':
- return `import { withTraceway } from "@tracewayapp/next";
+ return `// app/traceway-provider.tsx
+"use client";
-export default withTraceway({
- connectionString: "${connectionString}",
-});`;
+import { TracewayProvider } from "@tracewayapp/react";
+
+export function TracewayClientProvider({ children }: { children: React.ReactNode }) {
+ return (
+ <TracewayProvider connectionString="${connectionString}">
+ {children}
+ </TracewayProvider>
+ );
+}
+
+// app/layout.tsx
+import { TracewayClientProvider } from "./traceway-provider";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+ return (
+ <html>
+ <body>
+ <TracewayClientProvider>{children}</TracewayClientProvider>
+ </body>
+ </html>
+ );
+}`;
case 'nestjs':
return `import { Module } from "@nestjs/common";
@@ -225,17 +249,12 @@ init("${connectionString}");
// Distributed trace headers are injected into $.ajax() requests`;
case 'react-native':
- return `import { TracewayProvider, TracewayErrorBoundary } from "@tracewayapp/react-native";
+ return `import { TracewayProvider } from "@tracewayapp/react-native";
export default function App() {
return (
- <TracewayProvider
- connectionString="${connectionString}"
- options={{ version: "1.0.0" }}
- >
- <TracewayErrorBoundary fallback={<CrashScreen />}>
- <RootNavigator />
- </TracewayErrorBoundary>
+ <TracewayProvider connectionString="${connectionString}">
+ <RootNavigator />
</TracewayProvider>
);
}`;
@@ -432,6 +451,13 @@ captureException(new Error("Test error"));`;
case 'jquery':
return `import { captureException } from "@tracewayapp/jquery";
+captureException(new Error("Test error"));`;
+ case 'nextjs':
+ return `import { useTraceway } from "@tracewayapp/react";
+
+// In a client component
+"use client";
+const { captureException } = useTraceway();
captureException(new Error("Test error"));`;
case 'react-native':
return `import { useTraceway } from "@tracewayapp/react-native";