Add a simple Next.js reference integration example by niemyjski · Pull Request #153 · exceptionless/Exceptionless.JavaScript

niemyjski · 2026-03-25T13:42:10Z

Summary

This adds a small example/nextjs App Router reference app that shows an Exceptionless integration in a way that stays close to native Next.js conventions.

The example covers:

client startup in instrumentation-client.js
route transition logging via onRouterTransitionStart
client handled errors, unhandled rejections, and App Router error boundaries
server startup in instrumentation.js
uncaught server errors via onRequestError
explicit route-handler logging with request metadata and after()-based queue flushing
a small request adapter plus focused tests for the request-shape normalization

Why

We wanted a concrete Next.js example that helps answer two product questions:

what does an Exceptionless integration look like when it feels idiomatic to Next.js and Vercel developers?
how much framework-specific surface do we actually need before a dedicated @exceptionless/nextjs package is justified?

This PR deliberately keeps the example close to the framework file conventions and uses Exceptionless APIs directly in the integration points instead of layering on a large custom abstraction.

Implementation Notes

A few details are worth calling out explicitly:

The example uses @environment.data to attach Next.js-specific context like framework, router, runtime, and Vercel deployment metadata.
Request metadata is attached through a tiny adapter so the node client can enrich events from Next request shapes in a way that is similar to the existing Express flow.
The example currently imports the built SDK bundles from packages/browser/dist and packages/node/dist because the package entrypoints still re-export internal #/* imports that Next does not currently like in this setup.
The example runs next dev --webpack and next build --webpack for now. Turbopack still rejects the current node bundle path because of node-localstorage's dynamic require.
next.config.mjs contains a scoped webpack alias for source-map as an example-level workaround for the unused stacktrace-gps AMD branch. This keeps that workaround out of @exceptionless/browser itself.

Validation

npm test -- --project nextjs-example
npm run build --workspace=nextjs-example

Follow-ups

I think the main follow-up after this lands is not more example abstraction, but fixing the SDK packaging issues that forced the example to lean on built bundle imports and webpack mode. Once those are cleaned up, we can evaluate whether a thin @exceptionless/nextjs helper is still worth having.

Copilot

Pull request overview

Adds a small App Router Next.js reference app under example/nextjs demonstrating an idiomatic Exceptionless integration across client + server hooks, with a tiny request adapter and tests.

Changes:

Add example/nextjs reference app (instrumentation hooks, error boundaries, route handler logging/flush, UI).
Add a Next.js request-shape adapter plus focused Vitest coverage.
Wire the new example into repo tooling (Vitest project, clean script, gitignore, lockfile).

Reviewed changes

Copilot reviewed 19 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vitest.config.ts	Adds a dedicated Vitest project for the Next.js example tests.
package.json	Extends `clean` to remove Next.js `.next` build output.
package-lock.json	Adds the Next.js example workspace and its dependency tree.
.gitignore	Ignores the Next.js example `.next/` directory.
example/nextjs/package.json	Defines the `nextjs-example` workspace and its runtime dependencies/scripts.
example/nextjs/next.config.mjs	Adds example-level webpack alias workaround for `source-map`.
example/nextjs/lib/next-request.js	Implements request context normalization for Next request shapes.
example/nextjs/test/next-request.test.js	Tests request context normalization for both web `Request` and `onRequestError` payload shape.
example/nextjs/lib/exceptionless-server.js	Server-side Exceptionless startup + Next/Vercel environment enrichment plugin.
example/nextjs/lib/exceptionless-browser.js	Browser-side Exceptionless startup + Next environment enrichment plugin.
example/nextjs/instrumentation.js	Registers server instrumentation and submits events from `onRequestError`.
example/nextjs/instrumentation-client.js	Starts browser client and logs router transitions via `onRouterTransitionStart`.
example/nextjs/components/ClientDemoPanel.jsx	Client UI to trigger logs/errors and hit the demo route handler.
example/nextjs/app/page.jsx	Home page describing integration coverage and rendering the demo panel.
example/nextjs/app/layout.jsx	Root layout + metadata wiring and global CSS import.
example/nextjs/app/globals.css	Styling for the demo UI.
example/nextjs/app/error.jsx	Route-level App Router error boundary with Exceptionless capture for client-only errors.
example/nextjs/app/global-error.jsx	Root-level App Router error boundary with Exceptionless capture for client-only errors.
example/nextjs/app/server-component-error/page.jsx	Server-component error route to exercise `onRequestError`.
example/nextjs/app/api/demo/route.js	Demo route handler logging + request metadata + `after()` queue flush.
example/nextjs/README.md	Documentation for running and understanding the example integration.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

example/nextjs/instrumentation.js

scripts/resolve-package-imports.mjs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…mple" This reverts commit b462d7e.

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

example/nextjs/package.json

example/nextjs/README.md

Co-authored-by: Blake Niemyjski <bniemyjski@gmail.com>

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

example/nextjs/app/error.jsx

example/nextjs/app/global-error.jsx

example/nextjs/lib/exceptionless-server.js

example/nextjs/README.md

Copilot

Pull request overview

Copilot reviewed 18 out of 20 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

example/nextjs/package.json

Copilot · 2026-03-27T13:23:14Z

example/nextjs/app/error.jsx

+          await Exceptionless.createException(error).addTags("error-boundary").setProperty("handledBy", "app/error.jsx").submit();
+        } catch (submitError) {
+          console.error("Exceptionless route boundary capture failed", submitError);
+        }
+      })();


Inside the if (!error.digest) branch, error.digest is always falsy, so setting the digest property is redundant (and setProperty no-ops on undefined). Removing this line (or moving it behind a separate truthy check) would make the intent clearer.

example/nextjs/app/global-error.jsx

niemyjski requested a review from Copilot March 25, 2026 13:44

niemyjski self-assigned this Mar 25, 2026

niemyjski added enhancement documentation labels Mar 25, 2026

Copilot started reviewing on behalf of niemyjski March 25, 2026 13:44 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

example/nextjs/app/api/demo/route.js Show resolved Hide resolved

example/nextjs/instrumentation.js Outdated Show resolved Hide resolved

niemyjski force-pushed the feature/nextjs-reference-example branch from dd29ae9 to 08e97b7 Compare March 26, 2026 00:54

github-code-quality bot found potential problems Mar 26, 2026

View reviewed changes

scripts/resolve-package-imports.mjs Fixed Show fixed Hide fixed

niemyjski and others added 5 commits March 27, 2026 06:45

Add Next.js reference integration example

4034ae6

Format Next.js example files

1bb49af

Export bundles as package entry points and update Next.js example

784e7e9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add resolve-package-imports build step and update Next.js example

b462d7e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Revert "Add resolve-package-imports build step and update Next.js exa…

4351881

…mple" This reverts commit b462d7e.

niemyjski force-pushed the feature/nextjs-reference-example branch from 08e97b7 to 4351881 Compare March 27, 2026 11:48

pr feedback

e9854f8

niemyjski requested a review from Copilot March 27, 2026 12:56

Copilot started reviewing on behalf of niemyjski March 27, 2026 12:57 View session

niemyjski commented Mar 27, 2026

View reviewed changes

example/nextjs/app/api/demo/route.js Outdated Show resolved Hide resolved

niemyjski commented Mar 27, 2026

View reviewed changes

example/nextjs/app/api/demo/route.js Outdated Show resolved Hide resolved

niemyjski commented Mar 27, 2026

View reviewed changes

example/nextjs/package.json Outdated Show resolved Hide resolved

niemyjski commented Mar 27, 2026

View reviewed changes

example/nextjs/README.md Outdated Show resolved Hide resolved

Apply suggestions from code review

84b778d

Co-authored-by: Blake Niemyjski <bniemyjski@gmail.com>

Copilot AI reviewed Mar 27, 2026

View reviewed changes

pr feedback

106cd3b

niemyjski requested a review from Copilot March 27, 2026 13:15

Copilot started reviewing on behalf of niemyjski March 27, 2026 13:15 View session

niemyjski added 2 commits March 27, 2026 08:19

PR feedback

ba5b28b

lint fix

8167bae

Copilot AI reviewed Mar 27, 2026

View reviewed changes

niemyjski merged commit 3d03e4d into main Mar 27, 2026
11 checks passed

niemyjski deleted the feature/nextjs-reference-example branch March 27, 2026 13:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add a simple Next.js reference integration example#153

Add a simple Next.js reference integration example#153
niemyjski merged 10 commits intomainfrom
feature/nextjs-reference-example

niemyjski commented Mar 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

niemyjski commented Mar 25, 2026

Summary

Why

Implementation Notes

Validation

Follow-ups

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants