> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stacknext.space/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> StackNext documentation is written for developers using StackNext in a Next.js App Router project. Use the getting-started and guides sections to install and operate the product, and the reference section for CLI, configuration, MCP and package surfaces. Version-matched package API reference ships inside each npm package under node_modules/@stacknext/<package>/docs/ and is preferred over this site for installed-version APIs. Diagnostic findings are evidence, not confirmed root causes; regression comparisons are deterministic and report-only. Contributor and repository-maintenance documentation is not part of this site.

# Next.js integration

> How StackNext registers with Next.js, what it captures and how it coexists with an existing OpenTelemetry setup.

StackNext uses the documented Next.js `instrumentation.ts` hook. It does not
patch Next.js internals and does not read `NEXT_PRIVATE_*` variables.

## Registration path

1. `stacknext dev` starts the collector and the project's `dev` script.
2. Next.js loads `instrumentation.ts` and calls `register()`.
3. `registerStackNext()` checks for an existing OpenTelemetry provider.
4. StackNext attaches a span processor and exporter when it owns the provider.
5. Documented Next.js spans are normalized and sent to the loopback collector.
6. `onRequestError` sends redacted request errors.

The generated instrumentation checks `NEXT_RUNTIME === 'nodejs'` and imports
`@stacknext/next` dynamically so Edge bundles do not pull Node-only modules.
Edge instrumentation is not supported even though the import is guarded.

## What is captured

* Documented `next.*` request, route, render, fetch, action and proxy spans.
* HTTP attributes and parent ids preserved from Next.js.
* Drizzle or Prisma query events when an adapter is registered.
* Errors passed to the Next.js error hook.
* Custom spans and wrapped actions from `@stacknext/next`.

Unknown span types remain as verbose evidence. They are not mapped to guessed
semantics. See [instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md).

## Existing OpenTelemetry setup

`registerStackNext()` yields to an already-registered provider. Keep your
existing exporter and call StackNext from the existing `register()` hook:

```ts theme={null}
import {
  registerStackNext,
  onRequestError as stackNextOnRequestError,
} from '@stacknext/next'

export async function register() {
  // Keep your existing monitoring setup.
  await registerStackNext()
}

// Only when the file does not already export an error hook:
export const onRequestError = stackNextOnRequestError
```

If your provider owns the pipeline, StackNext cannot add a second SDK. Verify
what the collector receives with `stacknext status` and `stacknext coverage`.

## Supported versions

Next.js 15 and 16 with the App Router on the Node.js runtime. The supported peer
range is `>=15.0.0 <17`. A newer major prints a warning in `stacknext init` until
it is added to the validation matrix. See [compatibility](https://docs.stacknext.space/compatibility.md).

## Related

* [Installation](https://docs.stacknext.space/installation.md)
* [Instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md)
* [Custom instrumentation](https://docs.stacknext.space/custom-instrumentation.md)
* [Configuration](https://docs.stacknext.space/reference/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.