@deeptracer/nextjs 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,269 @@
+# @deeptracer/nextjs
+
+[![npm](https://img.shields.io/npm/v/@deeptracer/nextjs?color=blue)](https://www.npmjs.com/package/@deeptracer/nextjs)
+
+DeepTracer Next.js integration — automatic server-side error capture with one-file setup. The easiest way to add observability to a Next.js application.
+
+## Installation
+
+```bash
+npm install @deeptracer/nextjs
+```
+
+**Peer dependencies:** `next >=14`, `react >=18`, `react-dom >=18`
+
+## Quick Start (1 file, 5 lines)
+
+Create `instrumentation.ts` in your project root:
+
+```ts
+import { init } from "@deeptracer/nextjs"
+
+export const { register, onRequestError } = init({
+  product: "my-app",
+  service: "web",
+  environment: "production",
+  endpoint: "https://deeptracer.example.com",
+  apiKey: process.env.DEEPTRACER_API_KEY!,
+})
+```
+
+That's it. All server-side errors are now captured automatically.
+
+## What Gets Captured Automatically
+
+With just `instrumentation.ts`, the following are captured without any additional code:
+
+- **Server Component errors** — rendering failures in React Server Components
+- **Route Handler errors** — uncaught exceptions in `app/api/**/route.ts`
+- **Middleware errors** — failures in `middleware.ts` / `proxy.ts`
+- **Uncaught exceptions** — `process.on("uncaughtException")` in Node.js runtime
+- **Unhandled rejections** — `process.on("unhandledRejection")` in Node.js runtime
+
+## API Reference (Server)
+
+Import from `@deeptracer/nextjs`:
+
+### `init(config)`
+
+Initialize DeepTracer for Next.js. Returns `register` and `onRequestError` for direct re-export from `instrumentation.ts`.
+
+**Parameters:**
+- `config: NextjsConfig` — extends `LoggerConfig` with:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `captureGlobalErrors` | `boolean` | `true` | Capture uncaught exceptions and unhandled rejections via `process.on` (Node.js runtime only). |
+| `captureConsole` | `boolean` | `false` | Intercept `console.*` calls and forward to DeepTracer. |
+
+**Returns:** `{ register, onRequestError, logger }`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `register` | `() => void` | Called by Next.js on server start. Sets up error handlers. |
+| `onRequestError` | `(err, request, context) => Promise<void>` | Called by Next.js on every server-side error. |
+| `logger` | `Logger` | The Logger instance for manual logging, server actions, and route handlers. |
+
+```ts
+// instrumentation.ts
+import { init } from "@deeptracer/nextjs"
+
+const deeptracer = init({
+  product: "my-app",
+  service: "web",
+  environment: "production",
+  endpoint: "https://deeptracer.example.com",
+  apiKey: process.env.DEEPTRACER_API_KEY!,
+})
+
+export const { register, onRequestError } = deeptracer
+export const logger = deeptracer.logger
+```
+
+---
+
+### `withServerAction(logger, name, fn)`
+
+Wrap a Next.js Server Action with automatic tracing and error capture. Creates a span and catches errors (re-throws after reporting).
+
+```ts
+// app/actions.ts
+"use server"
+import { withServerAction } from "@deeptracer/nextjs"
+import { logger } from "@/instrumentation"
+
+export async function createUser(formData: FormData) {
+  return withServerAction(logger, "createUser", async () => {
+    const name = formData.get("name") as string
+    const user = await db.user.create({ data: { name } })
+    return user
+  })
+}
+```
+
+---
+
+### `withRouteHandler(logger, name, handler)`
+
+Wrap a Next.js Route Handler with automatic tracing and error capture. Creates a request-scoped span and extracts trace context from headers.
+
+```ts
+// app/api/users/route.ts
+import { withRouteHandler } from "@deeptracer/nextjs"
+import { logger } from "@/instrumentation"
+
+export const GET = withRouteHandler(logger, "GET /api/users", async (request) => {
+  const users = await db.user.findMany()
+  return Response.json(users)
+})
+
+export const POST = withRouteHandler(logger, "POST /api/users", async (request) => {
+  const body = await request.json()
+  const user = await db.user.create({ data: body })
+  return Response.json(user, { status: 201 })
+})
+```
+
+---
+
+### Re-exported from @deeptracer/node
+
+All exports from `@deeptracer/node` and `@deeptracer/core` are available:
+
+- `createLogger`, `Logger`, `captureGlobalErrors`, `captureConsole`, `honoMiddleware`, `expressMiddleware`
+- Types: `LoggerConfig`, `User`, `Breadcrumb`, `BeforeSendEvent`, `Span`, `InactiveSpan`, etc.
+- Constants: `SDK_VERSION`, `SDK_NAME`
+
+## API Reference (Client)
+
+Import from `@deeptracer/nextjs/client`:
+
+### `DeepTracerProvider`
+
+React context provider for client-side error capture. See [`@deeptracer/react`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/react) for full docs.
+
+```tsx
+// app/layout.tsx
+import { DeepTracerProvider } from "@deeptracer/nextjs/client"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <DeepTracerProvider config={{
+          product: "my-app",
+          service: "web",
+          environment: "production",
+          endpoint: process.env.NEXT_PUBLIC_DEEPTRACER_ENDPOINT!,
+          apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+        }}>
+          {children}
+        </DeepTracerProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+### `DeepTracerErrorPage`
+
+Drop-in error page for `error.tsx` / `global-error.tsx`.
+
+```tsx
+// app/global-error.tsx
+"use client"
+export { DeepTracerErrorPage as default } from "@deeptracer/nextjs/client"
+```
+
+### Other client exports
+
+- `DeepTracerErrorBoundary` — class-based error boundary for wrapping React trees
+- `useLogger()` — hook to access Logger from context
+- `useDeepTracerErrorReporter(error)` — hook for custom error pages
+
+## Full Setup (Server + Client)
+
+### 1. Server-side (required)
+
+```ts
+// instrumentation.ts
+import { init } from "@deeptracer/nextjs"
+
+const deeptracer = init({
+  product: "my-app",
+  service: "web",
+  environment: "production",
+  endpoint: "https://deeptracer.example.com",
+  apiKey: process.env.DEEPTRACER_API_KEY!,
+})
+
+export const { register, onRequestError } = deeptracer
+export const logger = deeptracer.logger
+```
+
+### 2. Client-side provider (optional)
+
+```tsx
+// app/layout.tsx
+import { DeepTracerProvider } from "@deeptracer/nextjs/client"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <DeepTracerProvider config={{
+          product: "my-app",
+          service: "web",
+          environment: "production",
+          endpoint: process.env.NEXT_PUBLIC_DEEPTRACER_ENDPOINT!,
+          apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+        }}>
+          {children}
+        </DeepTracerProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+### 3. Error boundary (optional)
+
+```tsx
+// app/global-error.tsx
+"use client"
+export { DeepTracerErrorPage as default } from "@deeptracer/nextjs/client"
+```
+
+## Environment Variables
+
+| Variable | Side | Description |
+|----------|------|-------------|
+| `DEEPTRACER_API_KEY` | Server | API key for server-side SDK |
+| `NEXT_PUBLIC_DEEPTRACER_ENDPOINT` | Client | Ingestion endpoint URL |
+| `NEXT_PUBLIC_DEEPTRACER_API_KEY` | Client | API key for client-side SDK |
+| `NEXT_PUBLIC_DEEPTRACER_PRODUCT` | Client | Product name (for zero-config provider) |
+| `NEXT_PUBLIC_DEEPTRACER_SERVICE` | Client | Service name (default: `"web"`) |
+| `NEXT_PUBLIC_DEEPTRACER_ENVIRONMENT` | Client | `"production"` or `"staging"` (default: `"production"`) |
+
+## Monorepo
+
+This package is part of the [DeepTracer JavaScript SDK](https://github.com/getdeeptracer/deeptracer-js) monorepo:
+
+| Package | Description |
+|---------|-------------|
+| [`@deeptracer/core`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/core) | Zero-dependency shared core |
+| [`@deeptracer/node`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/node) | Node.js/Bun SDK |
+| [`@deeptracer/ai`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/ai) | AI SDK wrappers |
+| [`@deeptracer/browser`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/browser) | Browser SDK |
+| [`@deeptracer/react`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/react) | React integration |
+| **`@deeptracer/nextjs`** | Next.js integration (this package) |
+
+## Links
+
+- [deeptracer.dev](https://deeptracer.dev) — Homepage
+- [Docs](https://deeptracer.dev/docs) — Documentation
+- [GitHub](https://github.com/getdeeptracer/deeptracer-js) — Source code
+
+## License
+
+MIT

package/dist/client.cjs

@@ -0,0 +1,38 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  DeepTracerErrorBoundary: () => import_react.DeepTracerErrorBoundary,
+  DeepTracerErrorPage: () => import_react.DeepTracerErrorPage,
+  DeepTracerProvider: () => import_react.DeepTracerProvider,
+  useDeepTracerErrorReporter: () => import_react.useDeepTracerErrorReporter,
+  useLogger: () => import_react.useLogger
+});
+module.exports = __toCommonJS(client_exports);
+var import_react = require("@deeptracer/react");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DeepTracerErrorBoundary,
+  DeepTracerErrorPage,
+  DeepTracerProvider,
+  useDeepTracerErrorReporter,
+  useLogger
+});

package/dist/client.d.cts

@@ -0,0 +1 @@
+export { DeepTracerErrorBoundary, DeepTracerErrorPage, DeepTracerProvider, DeepTracerProviderProps, useDeepTracerErrorReporter, useLogger } from '@deeptracer/react';

package/dist/client.d.ts

@@ -0,0 +1 @@
+export { DeepTracerErrorBoundary, DeepTracerErrorPage, DeepTracerProvider, DeepTracerProviderProps, useDeepTracerErrorReporter, useLogger } from '@deeptracer/react';

package/dist/client.js

@@ -0,0 +1,15 @@
+// src/client.ts
+import {
+  DeepTracerProvider,
+  DeepTracerErrorPage,
+  DeepTracerErrorBoundary,
+  useDeepTracerErrorReporter,
+  useLogger
+} from "@deeptracer/react";
+export {
+  DeepTracerErrorBoundary,
+  DeepTracerErrorPage,
+  DeepTracerProvider,
+  useDeepTracerErrorReporter,
+  useLogger
+};

package/dist/index.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -16,9 +20,146 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  init: () => init,
+  withRouteHandler: () => withRouteHandler,
+  withServerAction: () => withServerAction
+});
 module.exports = __toCommonJS(index_exports);
 __reExport(index_exports, require("@deeptracer/node"), module.exports);
+
+// src/init.ts
+var import_core = require("@deeptracer/core");
+function init(config) {
+  const logger = (0, import_core.createLogger)(config);
+  const shouldCaptureGlobalErrors = config.captureGlobalErrors !== false;
+  const shouldCaptureConsole = config.captureConsole === true;
+  function register() {
+    const runtime = typeof process !== "undefined" ? process.env?.NEXT_RUNTIME : void 0;
+    if (runtime === "nodejs") {
+      if (shouldCaptureGlobalErrors) {
+        process.on("uncaughtException", (error) => {
+          logger.captureError(error, {
+            severity: "critical",
+            context: { source: "uncaughtException", runtime: "nodejs" }
+          });
+          logger.flush();
+        });
+        process.on("unhandledRejection", (reason) => {
+          logger.captureError(
+            reason instanceof Error ? reason : new Error(String(reason)),
+            {
+              severity: "high",
+              context: { source: "unhandledRejection", runtime: "nodejs" }
+            }
+          );
+          logger.flush();
+        });
+      }
+      if (shouldCaptureConsole) {
+        const origLog = console.log;
+        const origInfo = console.info;
+        const origWarn = console.warn;
+        const origError = console.error;
+        const origDebug = console.debug;
+        console.log = (...args) => {
+          logger.info(args.map(String).join(" "));
+          origLog(...args);
+        };
+        console.info = (...args) => {
+          logger.info(args.map(String).join(" "));
+          origInfo(...args);
+        };
+        console.warn = (...args) => {
+          logger.warn(args.map(String).join(" "));
+          origWarn(...args);
+        };
+        console.error = (...args) => {
+          logger.error(args.map(String).join(" "));
+          origError(...args);
+        };
+        console.debug = (...args) => {
+          logger.debug(args.map(String).join(" "));
+          origDebug(...args);
+        };
+      }
+      logger.info("DeepTracer initialized", {
+        runtime: "nodejs",
+        product: config.product,
+        service: config.service
+      });
+    } else if (runtime === "edge") {
+      logger.info("DeepTracer initialized", {
+        runtime: "edge",
+        product: config.product,
+        service: config.service
+      });
+    }
+  }
+  async function onRequestError(err, request, context) {
+    const reqLogger = logger.withContext(
+      `${context.routeType}:${context.routePath}`
+    );
+    reqLogger.addBreadcrumb({
+      type: "http",
+      message: `${request.method} ${request.path}`
+    });
+    reqLogger.captureError(err, {
+      severity: "high",
+      context: {
+        source: "nextjs-onRequestError",
+        method: request.method,
+        path: request.path,
+        routerKind: context.routerKind,
+        routePath: context.routePath,
+        routeType: context.routeType
+      }
+    });
+  }
+  return { register, onRequestError, logger };
+}
+
+// src/server-action.ts
+async function withServerAction(logger, name, fn) {
+  return logger.startSpan(`server-action:${name}`, async () => {
+    try {
+      return await fn();
+    } catch (error) {
+      logger.captureError(error, {
+        severity: "high",
+        context: { source: "server-action", action: name }
+      });
+      throw error;
+    }
+  });
+}
+
+// src/route-handler.ts
+function withRouteHandler(logger, name, handler) {
+  return async (request) => {
+    const reqLogger = logger.forRequest(request);
+    return reqLogger.startSpan(`route:${name}`, async () => {
+      try {
+        return await handler(request);
+      } catch (error) {
+        reqLogger.captureError(error, {
+          severity: "high",
+          context: {
+            source: "route-handler",
+            route: name,
+            method: request.method,
+            url: request.url
+          }
+        });
+        throw error;
+      }
+    });
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  init,
+  withRouteHandler,
+  withServerAction,
   ...require("@deeptracer/node")
 });

package/dist/index.d.cts

@@ -1 +1,149 @@
 export * from '@deeptracer/node';
+import { Logger, LoggerConfig } from '@deeptracer/core';
+
+/**
+ * Configuration for the DeepTracer Next.js integration.
+ * Extends the base LoggerConfig with Next.js-specific options.
+ */
+interface NextjsConfig extends LoggerConfig {
+    /**
+     * Automatically capture uncaught exceptions and unhandled rejections
+     * via Node.js process events (only in Node.js runtime, not Edge).
+     * Default: true
+     */
+    captureGlobalErrors?: boolean;
+    /**
+     * Intercept console.log/warn/error/debug calls and forward them to DeepTracer.
+     * Default: false (can be noisy in development)
+     */
+    captureConsole?: boolean;
+}
+/**
+ * Return type of `init()`. Destructure `register` and `onRequestError`
+ * to re-export them from your `instrumentation.ts` file.
+ */
+interface InitResult {
+    /**
+     * Called by Next.js when the server starts.
+     * Sets up global error capture and console interception.
+     * Re-export this from your `instrumentation.ts`.
+     */
+    register: () => void;
+    /**
+     * Called by Next.js on every server-side error (Server Components,
+     * Route Handlers, Middleware). Captures errors and sends them to DeepTracer.
+     * Re-export this as `onRequestError` from your `instrumentation.ts`.
+     */
+    onRequestError: (err: Error, request: {
+        path: string;
+        method: string;
+        headers: Record<string, string>;
+    }, context: {
+        routerKind: string;
+        routePath: string;
+        routeType: string;
+    }) => Promise<void>;
+    /**
+     * The DeepTracer Logger instance. Use this for manual logging,
+     * error capture, or to pass to `withServerAction` / `withRouteHandler`.
+     *
+     * @example
+     * ```ts
+     * const deeptracer = init({ ... })
+     * export const { register, onRequestError } = deeptracer
+     * export const logger = deeptracer.logger
+     * ```
+     */
+    logger: Logger;
+}
+/**
+ * Initialize DeepTracer for Next.js. Returns `register` and `onRequestError`
+ * to be re-exported from your `instrumentation.ts` file.
+ *
+ * This is the **only setup required** for server-side error capture in Next.js.
+ * Every server-side error (Server Components, Route Handlers, Middleware) is
+ * automatically captured via Next.js's built-in `onRequestError` hook.
+ *
+ * @param config - Logger configuration with optional Next.js-specific options
+ * @returns Object with `register`, `onRequestError`, and `logger`
+ *
+ * @example
+ * Create `instrumentation.ts` in your project root:
+ * ```ts
+ * import { init } from "@deeptracer/nextjs"
+ *
+ * export const { register, onRequestError } = init({
+ *   product: "my-app",
+ *   service: "web",
+ *   environment: "production",
+ *   endpoint: "https://deeptracer.example.com",
+ *   apiKey: process.env.DEEPTRACER_API_KEY!,
+ * })
+ * ```
+ *
+ * That's it. All server-side errors are now captured automatically.
+ */
+declare function init(config: NextjsConfig): InitResult;
+
+/**
+ * Wrap a Next.js Server Action with automatic tracing and error capture.
+ *
+ * Creates a span for the action's execution and captures any errors.
+ * The original error is always re-thrown so Next.js error handling works normally.
+ *
+ * @param logger - DeepTracer Logger instance (from `init().logger`)
+ * @param name - A descriptive name for the action (e.g., "createUser", "submitForm")
+ * @param fn - The async function to execute
+ * @returns The result of the server action function
+ *
+ * @example
+ * ```ts
+ * // app/actions.ts
+ * "use server"
+ * import { withServerAction } from "@deeptracer/nextjs"
+ * import { logger } from "@/instrumentation"
+ *
+ * export async function createUser(formData: FormData) {
+ *   return withServerAction(logger, "createUser", async () => {
+ *     const name = formData.get("name") as string
+ *     const user = await db.user.create({ data: { name } })
+ *     return user
+ *   })
+ * }
+ * ```
+ */
+declare function withServerAction<T>(logger: Logger, name: string, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * Wrap a Next.js App Router Route Handler with automatic tracing and error capture.
+ *
+ * Creates a request-scoped span, extracts trace context from headers,
+ * and captures any errors. The original error is re-thrown so Next.js
+ * error handling works normally.
+ *
+ * @param logger - DeepTracer Logger instance (from `init().logger`)
+ * @param name - A descriptive name for the route (e.g., "GET /api/users")
+ * @param handler - The route handler function
+ * @returns A wrapped route handler function
+ *
+ * @example
+ * ```ts
+ * // app/api/users/route.ts
+ * import { withRouteHandler } from "@deeptracer/nextjs"
+ * import { logger } from "@/instrumentation"
+ *
+ * export const GET = withRouteHandler(logger, "GET /api/users", async (request) => {
+ *   const users = await db.user.findMany()
+ *   return Response.json(users)
+ * })
+ *
+ * export const POST = withRouteHandler(logger, "POST /api/users", async (request) => {
+ *   const body = await request.json()
+ *   const user = await db.user.create({ data: body })
+ *   return Response.json(user, { status: 201 })
+ * })
+ * ```
+ */
+declare function withRouteHandler(logger: Logger, name: string, handler: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
+
+export { type InitResult, type NextjsConfig, init, withRouteHandler, withServerAction };

package/dist/index.d.ts

@@ -1 +1,149 @@
 export * from '@deeptracer/node';
+import { Logger, LoggerConfig } from '@deeptracer/core';
+
+/**
+ * Configuration for the DeepTracer Next.js integration.
+ * Extends the base LoggerConfig with Next.js-specific options.
+ */
+interface NextjsConfig extends LoggerConfig {
+    /**
+     * Automatically capture uncaught exceptions and unhandled rejections
+     * via Node.js process events (only in Node.js runtime, not Edge).
+     * Default: true
+     */
+    captureGlobalErrors?: boolean;
+    /**
+     * Intercept console.log/warn/error/debug calls and forward them to DeepTracer.
+     * Default: false (can be noisy in development)
+     */
+    captureConsole?: boolean;
+}
+/**
+ * Return type of `init()`. Destructure `register` and `onRequestError`
+ * to re-export them from your `instrumentation.ts` file.
+ */
+interface InitResult {
+    /**
+     * Called by Next.js when the server starts.
+     * Sets up global error capture and console interception.
+     * Re-export this from your `instrumentation.ts`.
+     */
+    register: () => void;
+    /**
+     * Called by Next.js on every server-side error (Server Components,
+     * Route Handlers, Middleware). Captures errors and sends them to DeepTracer.
+     * Re-export this as `onRequestError` from your `instrumentation.ts`.
+     */
+    onRequestError: (err: Error, request: {
+        path: string;
+        method: string;
+        headers: Record<string, string>;
+    }, context: {
+        routerKind: string;
+        routePath: string;
+        routeType: string;
+    }) => Promise<void>;
+    /**
+     * The DeepTracer Logger instance. Use this for manual logging,
+     * error capture, or to pass to `withServerAction` / `withRouteHandler`.
+     *
+     * @example
+     * ```ts
+     * const deeptracer = init({ ... })
+     * export const { register, onRequestError } = deeptracer
+     * export const logger = deeptracer.logger
+     * ```
+     */
+    logger: Logger;
+}
+/**
+ * Initialize DeepTracer for Next.js. Returns `register` and `onRequestError`
+ * to be re-exported from your `instrumentation.ts` file.
+ *
+ * This is the **only setup required** for server-side error capture in Next.js.
+ * Every server-side error (Server Components, Route Handlers, Middleware) is
+ * automatically captured via Next.js's built-in `onRequestError` hook.
+ *
+ * @param config - Logger configuration with optional Next.js-specific options
+ * @returns Object with `register`, `onRequestError`, and `logger`
+ *
+ * @example
+ * Create `instrumentation.ts` in your project root:
+ * ```ts
+ * import { init } from "@deeptracer/nextjs"
+ *
+ * export const { register, onRequestError } = init({
+ *   product: "my-app",
+ *   service: "web",
+ *   environment: "production",
+ *   endpoint: "https://deeptracer.example.com",
+ *   apiKey: process.env.DEEPTRACER_API_KEY!,
+ * })
+ * ```
+ *
+ * That's it. All server-side errors are now captured automatically.
+ */
+declare function init(config: NextjsConfig): InitResult;
+
+/**
+ * Wrap a Next.js Server Action with automatic tracing and error capture.
+ *
+ * Creates a span for the action's execution and captures any errors.
+ * The original error is always re-thrown so Next.js error handling works normally.
+ *
+ * @param logger - DeepTracer Logger instance (from `init().logger`)
+ * @param name - A descriptive name for the action (e.g., "createUser", "submitForm")
+ * @param fn - The async function to execute
+ * @returns The result of the server action function
+ *
+ * @example
+ * ```ts
+ * // app/actions.ts
+ * "use server"
+ * import { withServerAction } from "@deeptracer/nextjs"
+ * import { logger } from "@/instrumentation"
+ *
+ * export async function createUser(formData: FormData) {
+ *   return withServerAction(logger, "createUser", async () => {
+ *     const name = formData.get("name") as string
+ *     const user = await db.user.create({ data: { name } })
+ *     return user
+ *   })
+ * }
+ * ```
+ */
+declare function withServerAction<T>(logger: Logger, name: string, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * Wrap a Next.js App Router Route Handler with automatic tracing and error capture.
+ *
+ * Creates a request-scoped span, extracts trace context from headers,
+ * and captures any errors. The original error is re-thrown so Next.js
+ * error handling works normally.
+ *
+ * @param logger - DeepTracer Logger instance (from `init().logger`)
+ * @param name - A descriptive name for the route (e.g., "GET /api/users")
+ * @param handler - The route handler function
+ * @returns A wrapped route handler function
+ *
+ * @example
+ * ```ts
+ * // app/api/users/route.ts
+ * import { withRouteHandler } from "@deeptracer/nextjs"
+ * import { logger } from "@/instrumentation"
+ *
+ * export const GET = withRouteHandler(logger, "GET /api/users", async (request) => {
+ *   const users = await db.user.findMany()
+ *   return Response.json(users)
+ * })
+ *
+ * export const POST = withRouteHandler(logger, "POST /api/users", async (request) => {
+ *   const body = await request.json()
+ *   const user = await db.user.create({ data: body })
+ *   return Response.json(user, { status: 201 })
+ * })
+ * ```
+ */
+declare function withRouteHandler(logger: Logger, name: string, handler: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
+
+export { type InitResult, type NextjsConfig, init, withRouteHandler, withServerAction };

package/dist/index.js

@@ -1,2 +1,136 @@
 // src/index.ts
 export * from "@deeptracer/node";
+
+// src/init.ts
+import { createLogger } from "@deeptracer/core";
+function init(config) {
+  const logger = createLogger(config);
+  const shouldCaptureGlobalErrors = config.captureGlobalErrors !== false;
+  const shouldCaptureConsole = config.captureConsole === true;
+  function register() {
+    const runtime = typeof process !== "undefined" ? process.env?.NEXT_RUNTIME : void 0;
+    if (runtime === "nodejs") {
+      if (shouldCaptureGlobalErrors) {
+        process.on("uncaughtException", (error) => {
+          logger.captureError(error, {
+            severity: "critical",
+            context: { source: "uncaughtException", runtime: "nodejs" }
+          });
+          logger.flush();
+        });
+        process.on("unhandledRejection", (reason) => {
+          logger.captureError(
+            reason instanceof Error ? reason : new Error(String(reason)),
+            {
+              severity: "high",
+              context: { source: "unhandledRejection", runtime: "nodejs" }
+            }
+          );
+          logger.flush();
+        });
+      }
+      if (shouldCaptureConsole) {
+        const origLog = console.log;
+        const origInfo = console.info;
+        const origWarn = console.warn;
+        const origError = console.error;
+        const origDebug = console.debug;
+        console.log = (...args) => {
+          logger.info(args.map(String).join(" "));
+          origLog(...args);
+        };
+        console.info = (...args) => {
+          logger.info(args.map(String).join(" "));
+          origInfo(...args);
+        };
+        console.warn = (...args) => {
+          logger.warn(args.map(String).join(" "));
+          origWarn(...args);
+        };
+        console.error = (...args) => {
+          logger.error(args.map(String).join(" "));
+          origError(...args);
+        };
+        console.debug = (...args) => {
+          logger.debug(args.map(String).join(" "));
+          origDebug(...args);
+        };
+      }
+      logger.info("DeepTracer initialized", {
+        runtime: "nodejs",
+        product: config.product,
+        service: config.service
+      });
+    } else if (runtime === "edge") {
+      logger.info("DeepTracer initialized", {
+        runtime: "edge",
+        product: config.product,
+        service: config.service
+      });
+    }
+  }
+  async function onRequestError(err, request, context) {
+    const reqLogger = logger.withContext(
+      `${context.routeType}:${context.routePath}`
+    );
+    reqLogger.addBreadcrumb({
+      type: "http",
+      message: `${request.method} ${request.path}`
+    });
+    reqLogger.captureError(err, {
+      severity: "high",
+      context: {
+        source: "nextjs-onRequestError",
+        method: request.method,
+        path: request.path,
+        routerKind: context.routerKind,
+        routePath: context.routePath,
+        routeType: context.routeType
+      }
+    });
+  }
+  return { register, onRequestError, logger };
+}
+
+// src/server-action.ts
+async function withServerAction(logger, name, fn) {
+  return logger.startSpan(`server-action:${name}`, async () => {
+    try {
+      return await fn();
+    } catch (error) {
+      logger.captureError(error, {
+        severity: "high",
+        context: { source: "server-action", action: name }
+      });
+      throw error;
+    }
+  });
+}
+
+// src/route-handler.ts
+function withRouteHandler(logger, name, handler) {
+  return async (request) => {
+    const reqLogger = logger.forRequest(request);
+    return reqLogger.startSpan(`route:${name}`, async () => {
+      try {
+        return await handler(request);
+      } catch (error) {
+        reqLogger.captureError(error, {
+          severity: "high",
+          context: {
+            source: "route-handler",
+            route: name,
+            method: request.method,
+            url: request.url
+          }
+        });
+        throw error;
+      }
+    });
+  };
+}
+export {
+  init,
+  withRouteHandler,
+  withServerAction
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deeptracer/nextjs",
-  "version": "0.2.0",
-  "description": "DeepTracer Next.js integration — server and client instrumentation (coming soon)",
+  "version": "0.3.1",
+  "description": "DeepTracer Next.js integration — automatic server-side error capture with one-file setup",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -11,11 +11,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "require": "./dist/client.cjs"
     }
   },
   "files": ["dist", "README.md"],
   "sideEffects": false,
-  "keywords": ["deeptracer", "nextjs", "observability"],
+  "keywords": ["deeptracer", "nextjs", "observability", "error-tracking", "instrumentation"],
   "repository": {
     "type": "git",
     "url": "https://github.com/getdeeptracer/deeptracer-js.git",
@@ -23,11 +28,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@deeptracer/node": "0.2.0",
-    "@deeptracer/react": "0.2.0"
+    "@deeptracer/node": "0.3.1",
+    "@deeptracer/react": "0.3.1"
   },
   "peerDependencies": {
-    "next": ">=14"
+    "next": ">=14",
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "scripts": {
     "build": "tsup",