Skip to main content
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

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

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: 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:

​
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 and CI integration.

​
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, not public issues.