@unhandled/nextjs 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @unhandled/nextjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sends traces, logs, metrics and server errors from a Next.js 15+ App Router app to Unhandled. It starts `@unhandled/node` from `instrumentation.ts` and reports errors through Next's `onRequestError` hook. Next's own request spans become the SERVER spans Unhandled groups by route.
+
+## Setup
+
+Set `UNHANDLED_DSN` (from the service settings page) in the server environment, then add three things.
+
+`instrumentation.ts` at the project root, or in `src/` when you use one:
+
+```ts
+export { register, onRequestError } from '@unhandled/nextjs'
+```
+
+`register` reads its options from the environment. To pass options, call `registerUnhandled` from your own `register`:
+
+```ts
+import { registerUnhandled } from '@unhandled/nextjs'
+
+export const register = () => {
+  registerUnhandled({ serviceName: 'storefront' })
+}
+
+export { onRequestError } from '@unhandled/nextjs'
+```
+
+`next.config.ts`:
+
+```ts
+import { withUnhandledConfig } from '@unhandled/nextjs'
+
+export default withUnhandledConfig({
+  // your config
+})
+```
+
+`withUnhandledConfig` adds `@unhandled/nextjs` and `@unhandled/node` to `serverExternalPackages` and keeps any entries you already have. Without it Next bundles a separate copy of the SDK into `instrumentation.ts` and into every route. The copies do not share state, so `setUser` cannot reach the request span and a server action error is reported twice. If you prefer to write the setting yourself, it is `serverExternalPackages: ['@unhandled/nextjs', '@unhandled/node']`.
+
+`registerUnhandled(options?)` takes every `@unhandled/node` option (`dsn`, `environment`, `serviceName`, `samplingRatio`, `http`, `instrumentations`, `integrations` and the rest) and returns the running client or `null`. It only starts the SDK when `NEXT_RUNTIME` is `nodejs`. On the edge runtime the package resolves to a build where `register`, `registerUnhandled`, `onRequestError`, `setUser` and `withServerAction` do nothing, so Edge routes and the edge compile of `instrumentation.ts` load no Node.js code and send nothing.
+
+Like `@unhandled/node`, it redacts secret query values and token-like path segments from URL attributes by default (`http.sanitizeUrls: false` turns that off), and reads source lines only from `.js`/`.ts` source files under the app root, never from paths named in an error message or from dotfiles such as `.env`. The [`@unhandled/node` README](../node/README.md#options) has the rules.
+
+## What you get
+
+Next opens a SERVER span for every request, named `GET /api/users/[id]`, with `http.route` set to the route pattern (`/api/users/[id]`, `/checkout`) and `next.route`, `http.method`, `http.target` and `http.status_code` next to it. Unhandled uses that span as the request.
+
+`onRequestError` reports errors thrown by route handlers, Server Components, server actions and the proxy with mechanism `nextjs.on_request_error` and `handled: false`. Each report carries these tags:
+
+| Tag | Value |
+| --- | --- |
+| `nextjs.route_path` | the route, for example `/api/boom` |
+| `nextjs.route_type` | `route`, `render`, `action` or `proxy` |
+| `nextjs.router_kind` | `App Router` or `Pages Router` |
+| `nextjs.render_source` | when rendering, for example `react-server-components` |
+| `nextjs.revalidate_reason` | `on-demand` or `stale` during revalidation |
+| `nextjs.digest` | the digest Next shows in place of the message in production |
+
+`notFound()`, `redirect()`, `permanentRedirect()`, `forbidden()`, `unauthorized()` and dynamic-rendering bailouts are control flow, not errors, and are never reported. The `ignoreExceptions`, `ignoreStatuses` and `ignoreCodes` options apply as well.
+
+## Users
+
+```ts
+import { setUser } from '@unhandled/nextjs'
+
+export const GET = async (request: Request) => {
+  const user = await currentUser(request)
+  setUser({ id: user.id, email: user.email })
+  return Response.json(user)
+}
+```
+
+`setUser` writes `user.id`, `user.email` and `user.name` on the active span and on the request's SERVER span.
+
+## Server actions
+
+Next names a server action request after the page that posts it (`POST /checkout`), so two actions on one page look the same. Wrap an action to give it a span of its own:
+
+```ts
+'use server'
+
+import { withServerAction } from '@unhandled/nextjs'
+
+export const submitOrder = withServerAction('submitOrder', async (form: FormData) => {
+  // ...
+})
+```
+
+The action runs inside a `server action submitOrder` span with the attribute `nextjs.server_action`. If it throws, the error is reported once with mechanism `nextjs.server_action` and the tag `nextjs.server_action`, then rethrown, so Next still renders its error. A `redirect()` or `notFound()` from the action passes through and does not mark the span as failed.
+
+Route handlers need no wrapper, because Next already names their spans by route and `onRequestError` already reports their errors.
+
+## Everything else
+
+`Unhandled.track`, `captureException`, `captureMessage`, `record` and the decorators come from `@unhandled/node`, which is installed with this package. Import them from there.

package/build/config.d.ts

@@ -0,0 +1,2 @@
+import type { NextConfig } from "next";
+export declare const withUnhandledConfig: (config?: NextConfig) => NextConfig;

package/build/config.js

@@ -0,0 +1,6 @@
+// Bundled copies would split SDK state between instrumentation.ts and each route's chunk.
+const SDK_PACKAGES = ["@unhandled/nextjs", "@unhandled/node"];
+export const withUnhandledConfig = (config = {}) => ({
+    ...config,
+    serverExternalPackages: [...new Set([...(config.serverExternalPackages ?? []), ...SDK_PACKAGES])],
+});

package/build/edge.d.ts

@@ -0,0 +1,8 @@
+import type * as Node from "./index.ts";
+export { withUnhandledConfig } from "./config.ts";
+export type { NextUnhandledOptions } from "./index.ts";
+export declare const registerUnhandled: typeof Node.registerUnhandled;
+export declare const register: typeof Node.register;
+export declare const onRequestError: typeof Node.onRequestError;
+export declare const setUser: typeof Node.setUser;
+export declare const withServerAction: typeof Node.withServerAction;

package/build/edge.js

@@ -0,0 +1,6 @@
+export { withUnhandledConfig } from "./config.js";
+export const registerUnhandled = () => null;
+export const register = () => undefined;
+export const onRequestError = () => undefined;
+export const setUser = () => undefined;
+export const withServerAction = (_name, action) => action;

package/build/errors.d.ts

@@ -0,0 +1,4 @@
+import { type Mechanism } from "@unhandled/node/framework";
+import type { Instrumentation } from "next";
+export declare const reportNextError: (error: unknown, mechanism: Mechanism, tags: Record<string, string>) => void;
+export declare const onRequestError: Instrumentation.onRequestError;

package/build/errors.js

@@ -0,0 +1,42 @@
+import { reportException } from "@unhandled/node/framework";
+// unstable_rethrow cannot load from an external package, so match its digests (plus 15.0's NEXT_NOT_FOUND).
+const SIGNAL_DIGESTS = new Set([
+    "NEXT_NOT_FOUND",
+    "BAILOUT_TO_CLIENT_SIDE_RENDERING",
+    "DYNAMIC_SERVER_USAGE",
+    "HANGING_PROMISE_REJECTION",
+    "NEXT_PRERENDER_INTERRUPTED",
+]);
+const SIGNAL_PREFIXES = ["NEXT_REDIRECT;", "NEXT_HTTP_ERROR_FALLBACK;"];
+const digestOf = (error) => {
+    const digest = typeof error === "object" && error !== null ? Reflect.get(error, "digest") : undefined;
+    return typeof digest === "string" ? digest : undefined;
+};
+const isNextSignal = (error) => {
+    const digest = digestOf(error);
+    if (digest !== undefined &&
+        (SIGNAL_DIGESTS.has(digest) || SIGNAL_PREFIXES.some((prefix) => digest.startsWith(prefix)))) {
+        return true;
+    }
+    return error instanceof Error && error.cause !== undefined && isNextSignal(error.cause);
+};
+export const reportNextError = (error, mechanism, tags) => {
+    if (isNextSignal(error)) {
+        return;
+    }
+    const digest = digestOf(error);
+    reportException(error, {
+        mechanism,
+        handled: false,
+        tags: { ...tags, ...(digest && { "nextjs.digest": digest }) },
+    });
+};
+export const onRequestError = (error, _request, context) => {
+    reportNextError(error, "nextjs.on_request_error", {
+        "nextjs.router_kind": context.routerKind,
+        "nextjs.route_path": context.routePath,
+        "nextjs.route_type": context.routeType,
+        ...(context.renderSource && { "nextjs.render_source": context.renderSource }),
+        ...(context.revalidateReason && { "nextjs.revalidate_reason": context.revalidateReason }),
+    });
+};

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export { setUser } from "@unhandled/node";
+export { withUnhandledConfig } from "./config.ts";
+export { onRequestError } from "./errors.ts";
+export { type NextUnhandledOptions, register, registerUnhandled } from "./register.ts";
+export { withServerAction } from "./server_action.ts";

package/build/index.js

@@ -0,0 +1,5 @@
+export { setUser } from "@unhandled/node";
+export { withUnhandledConfig } from "./config.js";
+export { onRequestError } from "./errors.js";
+export { register, registerUnhandled } from "./register.js";
+export { withServerAction } from "./server_action.js";

package/build/register.d.ts

@@ -0,0 +1,5 @@
+import { type UnhandledClient } from "@unhandled/node";
+import { type UnhandledOptions } from "@unhandled/node/framework";
+export type NextUnhandledOptions = Omit<UnhandledOptions, "frameworkLayer">;
+export declare const registerUnhandled: (options?: NextUnhandledOptions) => UnhandledClient | null;
+export declare const register: () => void;

package/build/register.js

@@ -0,0 +1,14 @@
+import { init } from "@unhandled/node";
+import { frameworkLayer } from "@unhandled/node/framework";
+export const registerUnhandled = (options = {}) => {
+    if (process.env.NEXT_RUNTIME !== "nodejs") {
+        return null;
+    }
+    return init({
+        ...options,
+        frameworkLayer: frameworkLayer(new URL("../package.json", import.meta.url), "nextjs"),
+    });
+};
+export const register = () => {
+    registerUnhandled();
+};

package/build/server_action.d.ts

@@ -0,0 +1 @@
+export declare const withServerAction: <Args extends unknown[], Result>(name: string, action: (...args: Args) => Promise<Result>) => (...args: Args) => Promise<Result>;

package/build/server_action.js

@@ -0,0 +1,15 @@
+import { trace } from "@opentelemetry/api";
+import { reportNextError } from "./errors.js";
+const tracer = trace.getTracer("@unhandled/nextjs");
+export const withServerAction = (name, action) => (...args) => tracer.startActiveSpan(`server action ${name}`, { attributes: { "nextjs.server_action": name } }, async (span) => {
+    try {
+        return await action(...args);
+    }
+    catch (error) {
+        reportNextError(error, "nextjs.server_action", { "nextjs.server_action": name });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+});

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@unhandled/nextjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Unhandled for Next.js: instrumentation.ts registration, request error reporting, route handler and server action wrappers on @unhandled/node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/treboryx/unhandled.git",
+    "directory": "packages/nextjs"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "edge-light": {
+        "types": "./build/edge.d.ts",
+        "default": "./build/edge.js"
+      },
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "~1.9.1",
+    "@unhandled/node": "0.0.1"
+  },
+  "devDependencies": {
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@types/node": "^25.9.9",
+    "@types/react": "^19.3.0",
+    "@unhandled/otlp-receiver": "0.0.0",
+    "next": "^16.4.2",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "~6.0.2"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "react": ">=19.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "node --test 'tests/**/*.test.ts'",
+    "typecheck": "tsrs --noEmit",
+    "typecheck:tsc": "tsc --noEmit"
+  }
 }