> ## 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.

# Compatibility

> Supported Node.js, Next.js 15 and 16, package manager, Playwright and MCP client combinations, plus what StackNext does not support.

StackNext targets Next.js App Router applications on the Node.js runtime. This
page separates combinations that were exercised during release validation from
combinations that are expected to work but were not part of the recorded matrix.

Last validation: **2026-11-03**.

## Supported surface

| Component | Supported |
| - | - |
| Next.js | 15 and 16, App Router only |
| Runtime | Node.js runtime |
| Node.js engine | `>=20.9.0` |
| Module format | ESM packages; CommonJS `require()` is not supported |
| Operating system | Linux (full e2e); Windows and macOS (package smoke in CI) |
| Package managers | npm and pnpm (validated); yarn and bun detection is best-effort |

The supported Next.js peer range is `>=15.0.0 <17`. A newer major prints a
warning in `stacknext init`; it is not treated as supported until it is added to
the validation matrix.

### Not supported

* Next.js Pages Router.
* The Edge runtime for instrumentation, Drizzle/Prisma adapters or the StackNext
  transport.
* Hosted or multi-user deployments. The collector binds to loopback and is
  designed for one developer machine.
* Parallel Playwright workers during a captured regression run.
* CommonJS consumers.
* Statistical significance or causal claims from regression comparisons.

## Validated package versions

| Tool | Version used in validation |
| - | - |
| Node.js | 22.23.3, 24.21.0 (primary) and 26.13.0 |
| pnpm | 12.16.1 |
| npm | 11.19.0 (Node 24) and 11.20.0 (Node 26) |
| Next.js | 16.4.3 and 15.5.28 |
| React | 19.3.1 |
| TypeScript | 5.9.3 |
| Playwright | 1.58.2 |
| Drizzle ORM | 0.45.4 |
| Prisma Client | 7.10.1 |
| better-sqlite3 | 13.0.3 |

The published packages declare Node.js `>=20.9.0` for compatibility with
existing applications. Node.js 20 is end-of-life; use Node.js 22 or newer for a
new installation. CI covers Node.js 22, 24 and 26.

## Validated consumer matrix

The external consumer smoke test installs the real package archives into a
fixture outside the pnpm workspace:

| Node.js | Next.js | npm | pnpm |
| - | - | - | - |
| 22.23.3 | 16.4.3 | Pass | Pass |
| 22.23.3 | 15.5.28 | Pass | Pass |
| 24.21.0 | 16.4.3 | Pass | Pass |
| 24.21.0 | 15.5.28 | Pass | Pass |
| 26.13.0 | 16.4.3 | Pass | Pass |
| 26.13.0 | 15.5.28 | Pass | Pass |

Each combination checks `init`, idempotent re-init, `doctor`, dashboard hosting
and static assets, real request telemetry, `status`, `coverage`, `diagnose`, an
MCP handshake with 20 read-only tools and 5 prompts, clean shutdown and
`uninstall`.

## Next.js 15 and 16

Both major versions are exercised by the external consumer smoke test. Next.js
15 uses webpack for the instrumentation bundle; Next.js 16 uses Turbopack by
default. StackNext avoids the `node:` URL scheme in modules reachable from
`instrumentation.ts` so both bundlers can compile the hook. Applications that
add their own Edge middleware should still keep StackNext imports behind the
generated `NEXT_RUNTIME === 'nodejs'` guard.

## Package matrix

All ten packages are published at the same version:

| Package | Runtime role | Peer / dependency notes |
| - | - | - |
| `@stacknext/cli` | CLI and collector | Depends on core, diagnostics, regression, mcp and dashboard |
| `@stacknext/next` | Instrumentation and exporter | Peer `next >=15 <17` |
| `@stacknext/core` | Shared types, redaction, transport | Base package |
| `@stacknext/diagnostics` | Deterministic findings | Used by CLI, MCP and dashboard |
| `@stacknext/regression` | Capture/baseline/comparison records | Used by CLI, MCP, dashboard and Playwright |
| `@stacknext/dashboard` | Static dashboard assets | Installed by the CLI |
| `@stacknext/mcp` | Read-only stdio MCP server | Installed by the CLI |
| `@stacknext/drizzle` | Drizzle adapter | Optional peer `drizzle-orm` |
| `@stacknext/prisma` | Prisma adapter | Optional peer `@prisma/client` |
| `@stacknext/playwright` | Playwright fixtures | Optional peer `@playwright/test >=1.40 <2` |

## Regression testing

* Use one Playwright worker for captured runs. Parallel correlation is not
  verified.
* Use at least three samples per scenario.
* A baseline and candidate must come from matching environments to produce a
  conclusive comparison.
* Warm `/`, the project route and a database-heavy API route before capturing a
  baseline so one-time route-module spans do not appear on only one side.
* Comparison statuses are `improved`, `regressed`, `unchanged` and
  `inconclusive`. `inconclusive` is not a pass.

See [regression testing](https://docs.stacknext.space/regression-testing.md) and
[CI integration](https://docs.stacknext.space/ci-integration.md).

## Reporting a compatibility problem

Open an issue with the StackNext version, Node.js version, Next.js version,
package manager, OS, the output of `stacknext doctor --json` and the smallest
reproduction you can share. Remove tokens, URLs with query values, customer data
and any captured records before posting. Security reports follow
[SECURITY.md](https://github.com/marrrkkk/stacknext/blob/main/SECURITY.md), not
public issues.


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