Adds client diagnostics and trace correlation for Route Handlers. Server Action traces are collected on the server and require an onTrace callback for access; they are not automatically joined to the browser timeline.

📥 Installation

npm install @traceora/next

✨ Exports

| Export | Type | Description | |---|---|---| | <TraceoraNextProvider> | Client Component | Frontend provider — initializes tracing, instruments fetch/XHR, adds DevTools overlay. | | withTraceora() | HOF | Wraps Route Handlers to establish a backend trace context and inject events into the response. | | traceAction() | HOF | Captures a Server Action and nested backend events; provide onTrace to receive its server-local events. | | emitTraceEvent() | Function | Manually emit a backend event within a traced request. | | traceoraPrismaExtension() | Prisma Extension | Auto-traces every Prisma query within a request. | | traceoraMongoosePlugin | Mongoose Plugin | Auto-traces every Mongoose operation within a request. |

🔧 Usage

1. Client Provider

Wrap your root layout to enable frontend tracing:

// app/layout.tsx
import { TraceoraNextProvider } from '@traceora/next/client';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TraceoraNextProvider>
          {children}
        </TraceoraNextProvider>
      </body>
    </html>
  );
}

2. Trace Route Handlers

Wrap your API routes with withTraceora to bridge backend events to the frontend:

// app/api/users/route.ts
import { NextResponse } from 'next/server';
import { withTraceora, emitTraceEvent } from '@traceora/next';

export const GET = withTraceora(async (req: Request) => {
  emitTraceEvent({
    type: 'STATE_CHANGE',
    source: 'Next.js API',
    metadata: { info: 'Fetching users...' },
  });

  return NextResponse.json({ users: [] });
});

3. Trace Server Actions

Wrap Server Actions with traceAction to capture execution time and receive the resulting server-local events:

'use server';
import { traceAction } from '@traceora/next';

export const createUser = traceAction('createUserAction', async (data: unknown) => {
  // Your action logic...
  return { success: true };
}, (events) => {
  // Forward to your own development logger or storage if needed.
  console.debug(events);
});

traceAction does not automatically return its events to the browser or correlate them with a client trace.

4. Auto-Track Database Queries

Plug in your ORM — every query is traced automatically:

import { PrismaClient } from '@prisma/client';
import { traceoraPrismaExtension } from '@traceora/next';

const prisma = new PrismaClient().$extends(traceoraPrismaExtension());

import mongoose from 'mongoose';
import { traceoraMongoosePlugin } from '@traceora/next';

mongoose.plugin(traceoraMongoosePlugin);

🔗 Related Packages

| Package | Role | |---|---| | @traceora/core | The underlying event engine | | @traceora/react | React bindings (used internally by the Next.js provider) | | @traceora/node | Shared backend primitives (AsyncLocalStorage, DB plugins) |