Add Next.js reference integration example

Author: niemyjski

.gitignore

@@ -12,3 +12,5 @@ packages/node/test-data
 
 yarn.lock
 .exceptionless
+
+example/nextjs/.next/

example/nextjs/README.md

@@ -0,0 +1,52 @@
+## Exceptionless for Next.js
+
+This example is a very small App Router site that shows the Exceptionless integration shape we want for a Next.js app: simple setup, rich metadata, and clear client/server error coverage.
+
+- `instrumentation-client.js` for browser startup and navigation logging
+- `instrumentation.js` for server startup and `onRequestError`
+- `app/error.jsx` for route-level client render failures
+- `app/global-error.jsx` for root-level client render failures
+- `app/api/demo/route.js` for explicit server-side logging from a route handler
+
+### What it covers
+
+- Manual client logs with structured data
+- Handled client exceptions submitted from a `try`/`catch`
+- Unhandled client promise rejections captured by the browser global handler
+- A client transition crash that lands in `app/error.jsx`
+- A server route log enriched with request headers, IP, path, query string, and JSON body
+- An unhandled route handler error captured by `onRequestError`
+- A server component render error captured by `onRequestError`
+
+### Why it is shaped this way
+
+This sticks to the native Next.js file boundaries instead of inventing another framework layer:
+
+- `instrumentation-client.js` is where client-side monitoring starts before the app becomes interactive.
+- `instrumentation.js` and `onRequestError` are where uncaught server render, route handler, server action, and proxy errors are captured.
+- `app/error.jsx` and `app/global-error.jsx` stay responsible for client render failures inside the App Router.
+- Route handlers submit logs directly with `Exceptionless.createLog(...)`, the environment module memoizes `Exceptionless.startup(...)`, and the server flushes with `Exceptionless.processQueue()` when needed.
+
+### Vercel-specific notes
+
+- The server helper flushes the Exceptionless queue explicitly. That matters for short-lived serverless runtimes where a background timer may not get enough time to send queued events.
+- The route handler uses `after()` so normal server logs flush after the response is sent.
+- The example locally aliases `source-map` to `false` in `next.config.mjs` so an unused `stacktrace-gps` AMD branch does not leak a `source-map` dependency into `@exceptionless/browser`.
+- The helper files import the built ESM bundles from `packages/browser/dist/index.bundle.js` and `packages/node/dist/index.bundle.js` because the package entrypoints still re-export internal `#/*` imports. The example also uses `--webpack` because Turbopack currently rejects the node bundle during page data collection on `node-localstorage`'s dynamic `require`.
+- If we later package this for production ergonomics, the clean split is likely a very thin `@exceptionless/nextjs` helper for framework hooks plus an optional `@exceptionless/vercel` add-on for `@vercel/otel`, deployment metadata, and queue-flush helpers.
+
+### Environment variables
+
+Set the env vars you want the example to use:
+
+- `NEXT_PUBLIC_EXCEPTIONLESS_API_KEY`
+- `NEXT_PUBLIC_EXCEPTIONLESS_SERVER_URL`
+- `EXCEPTIONLESS_API_KEY`
+- `EXCEPTIONLESS_SERVER_URL`
+
+### Run locally
+
+1. `npm install`
+2. `npm run build`
+3. `cd example/nextjs`
+4. `npm run dev`

example/nextjs/app/api/demo/route.js

@@ -0,0 +1,31 @@
+import { after } from "next/server";
+
+import { Exceptionless, KnownEventDataKeys, startup } from "../../../lib/exceptionless-server.js";
+import { buildRequestContextFromRequest } from "../../../lib/next-request.js";
+
+export async function POST(request) {
+  const parsedBody = await request.json().catch(() => ({}));
+  const body = typeof parsedBody === "object" && parsedBody !== null ? parsedBody : { value: parsedBody };
+  const mode = typeof body.mode === "string" ? body.mode : "log";
+
+  if (mode === "error") {
+    throw new Error("Route handler crash from the Exceptionless Next.js demo");
+  }
+
+  await startup();
+
+  const builder = Exceptionless.createLog("nextjs.route", "Route handler log from the demo page", "info").addTags("route-handler");
+
+  builder.setContextProperty(KnownEventDataKeys.RequestInfo, buildRequestContextFromRequest(request, body));
+
+  await builder.submit();
+
+  after(async () => {
+    await Exceptionless.processQueue();
+  });
+
+  return Response.json({
+    ok: true,
+    message: "Server route log submitted. The queue will flush in next/after()."
+  });
+}

example/nextjs/app/error.jsx

@@ -0,0 +1,47 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect } from "react";
+
+import { Exceptionless, startup } from "../lib/exceptionless-browser.js";
+
+export default function ErrorPage({ error, reset }) {
+  useEffect(() => {
+    if (!error.digest) {
+      void (async () => {
+        try {
+          await startup();
+          await Exceptionless.createException(error)
+            .addTags("error-boundary")
+            .setProperty("handledBy", "app/error.jsx")
+            .setProperty("digest", error.digest)
+            .submit();
+        } catch (submitError) {
+          console.error("Exceptionless route boundary capture failed", submitError);
+        }
+      })();
+    }
+  }, [error]);
+
+  return (
+    <main className="error-shell">
+      <section className="panel error-card">
+        <div className="panel-body">
+          <p className="eyebrow">Route Error Boundary</p>
+          <h1>Something inside this route broke.</h1>
+          <p>
+            Client-only render errors are submitted here. Server-rendered failures already have a digest and are captured by
+            `instrumentation.js` through `onRequestError`.
+          </p>
+          <div className="error-actions">
+            <button type="button" onClick={() => reset()}>
+              Retry this route
+            </button>
+            <Link href="/">Back to the example</Link>
+          </div>
+          {error.digest ? <p className="error-digest">Server digest: {error.digest}</p> : null}
+        </div>
+      </section>
+    </main>
+  );
+}

example/nextjs/app/global-error.jsx

@@ -0,0 +1,51 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect } from "react";
+
+import { Exceptionless, startup } from "../lib/exceptionless-browser.js";
+
+export default function GlobalError({ error, reset }) {
+  useEffect(() => {
+    if (!error.digest) {
+      void (async () => {
+        try {
+          await startup();
+          await Exceptionless.createException(error)
+            .addTags("error-boundary")
+            .setProperty("handledBy", "app/global-error.jsx")
+            .setProperty("digest", error.digest)
+            .submit();
+        } catch (submitError) {
+          console.error("Exceptionless global boundary capture failed", submitError);
+        }
+      })();
+    }
+  }, [error]);
+
+  return (
+    <html lang="en">
+      <body>
+        <main className="error-shell">
+          <section className="panel error-card">
+            <div className="panel-body">
+              <p className="eyebrow">Global Error Boundary</p>
+              <h1>The root layout failed.</h1>
+              <p>
+                This is the last-resort client boundary for the App Router. In normal server-rendered failures we still prefer the
+                richer `onRequestError` path.
+              </p>
+              <div className="error-actions">
+                <button type="button" onClick={() => reset()}>
+                  Retry the app shell
+                </button>
+                <Link href="/">Back to the example</Link>
+              </div>
+              {error.digest ? <p className="error-digest">Server digest: {error.digest}</p> : null}
+            </div>
+          </section>
+        </main>
+      </body>
+    </html>
+  );
+}