Collect
Next.js emits spans for routes, renders and fetches. StackNext picks them up and adds Drizzle or Prisma query events and server errors.
Open source · MIT
Debug Next.js requestson your machine.
StackNext collects the spans Next.js already emits, plus Drizzle and Prisma query events and server errors. Follow any request through the dashboard, CLI or a read-only MCP server.
npm install --save-dev @stacknext/cli @stacknext/nextStackNext / Overview
Works with your existing stack
Adapters for Drizzle, Prisma and Playwright are optional.
- Next.js 15 / 16App Router
- OpenTelemetryDocumented spans
- DrizzleQuery logger
- PrismaQuery events
- PlaywrightScenario capture
- MCPRead-only
01 / How it works
Follow one request
through the stack.
Next.js already emits the spans. StackNext adds query events and errors, then ties everything to the request that produced it. The result is a fixed-size sample that stays in memory.
Fig 0.1System
Correlate
Queries and errors are attached to the request that produced them, so a slow route leads to the span or query inside it.
Inspect
Open a request in the dashboard and move from route to span to query. The CLI and MCP server read the same data.
02 / System
One Node process127.0.0.1:4400Memory onlyFiles under .stacknext
The collector is one Node process.
It listens on loopback, keeps a fixed-size window in memory, and writes runs, baselines, comparisons and snapshots under .stacknext. There is no backend to deploy.
- Runtime
- Next.js 15/16 · Node.js 20.9+
- Collector
- 127.0.0.1:4400
- Store
- 5,000 spans · 10 minutes
- Diagnostics
- 6 deterministic rules
- Snapshots
- 64 MiB each · autoKeep 10
- Records
- 16 MiB per file
- MCP
- 20 read-only tools · 5 prompts
03 / Access
Read it where
you work.
The dashboard, CLI and MCP server all read the same local sample. Start in the browser, script a check, or hand the data to your coding agent.
01
Dashboard
The full sample: requests, traces, database queries, errors, diagnostics, snapshots and saved test runs.
stacknext devSee the dashboard02
CLI
Coverage, diagnostics, exports, snapshots, captures and comparisons from a terminal.
stacknext diagnoseCLI reference03
MCP
A read-only server for coding agents: 20 tools, 5 prompts and GET requests over loopback.
stacknext mcpMCP reference04 / Dashboard
A tour of the
dashboard.
Every screenshot here is a real capture from the example app.
StackNext / OverviewWINDOWS CHROME · DARK
01 / Overview
The current sample at a glance.
Requests, latency, database activity, errors, coverage and open findings, with the retention window always visible.
- The store is capped, and drop counters show when it fills.
- Coverage reports what this sample observed, not a score.
- Updates live while the collector runs.
Windows Chrome · dark · 1600 × 1000
StackNext / TracesWINDOWS CHROME · DARK
02 / Traces
Follow a request through its spans.
Open a route to see status, duration, server spans, database queries and any correlated errors on one timeline.
- Built from documented Next.js telemetry only.
- Manual span helpers preserve return values and errors.
- Missing parents are reported, never guessed.
Windows Chrome · dark · 1600 × 1000
StackNext / DatabaseWINDOWS CHROME · DARK
03 / Database
See the query without the values.
Drizzle and Prisma events share the request timeline. SQL text is redacted, and bind parameters are never captured.
- Repeated query shapes surface as N+1 signals.
- Drizzle durations are marked unmeasured, not zero.
- Slow query spans keep their documented attributes.
Windows Chrome · dark · 1600 × 1000
StackNext / DiagnosticsWINDOWS CHROME · DARK
04 / Diagnostics
Findings with the evidence attached.
Six rules run over the current sample: N+1 queries, slow requests, slow spans, repeated external HTTP, error fingerprints and server error responses.
- Findings are marked possible or observed, never confirmed root causes.
- Evidence is capped and re-sanitized before it is shown.
- Read the evidence and limits before you change code.
Windows Chrome · dark · 1600 × 1000
StackNext / RegressionWINDOWS CHROME · DARK
05 / Regression
Check a flow against a baseline.
Playwright scenarios are tied to the server trace that ran them, then compared with a saved baseline using medians and explicit thresholds.
- Correlation needs the injected trace id and a matching parent span.
- Ambiguous samples make the comparison inconclusive.
- Report-only unless you pass --fail-on.
Windows Chrome · dark · 1600 × 1000
Showing Overview: The current sample at a glance.
05 / Install
Add it to your app.
Keep your instrumentation.
Three commands from install to a live request sample.
- 01
Install the packages
Run this inside the Next.js app, not at the workspace root.
npm install --save-dev @stacknext/cli @stacknext/next - 02
Run init
initwritesstacknext.config.jsonand createsinstrumentation.tsif it doesn't exist.npx stacknext init - 03
Start the collector
devstarts the collector, runs your app's dev script, and writes a short-lived token to.stacknext/run.jsonwith mode0600.npx stacknext dev
init never overwrites an existing instrumentation file. If another monitor already owns it, add StackNext inside it.
instrumentation.tsDocs
type StackNextRequest = { path: string method: string headers: NodeJS.Dict<string | string[]>} type StackNextRequestContext = { routerKind: 'Pages Router' | 'App Router' routePath: string routeType: 'render' | 'route' | 'action' | 'proxy' renderSource?: string revalidateReason: 'on-demand' | 'stale' | undefined} // Generated by StackNext. Node.js runtime only; no-op without a local collector.export async function register(): Promise<void> { if (process.env.NEXT_RUNTIME !== 'nodejs') return const stacknext = await import('@stacknext/next') await stacknext.register()} export async function onRequestError( error: unknown, request: StackNextRequest, context: StackNextRequestContext,): Promise<void> { if (process.env.NEXT_RUNTIME !== 'nodejs') return const stacknext = await import('@stacknext/next') stacknext.onRequestError(error, request, context)}Generated by stacknext init. If instrumentation.ts already exists, init prints the lines to add instead.
lib/db.tsDocs
import { drizzle } from 'drizzle-orm/better-sqlite3'import { createStackNextDrizzleLogger } from '@stacknext/drizzle' export const db = drizzle(client, { logger: createStackNextDrizzleLogger({ databaseSystem: 'sqlite' }),})Drizzle's Logger interface doesn't expose query duration. StackNext stores null and marks it as unmeasured.
lib/prisma.tsDocs
import { PrismaClient } from '@prisma/client'import { instrumentPrismaClient } from '@stacknext/prisma' const prisma = new PrismaClient({ log: [{ emit: 'event', level: 'query' }],}) const stop = instrumentPrismaClient(prisma, { databaseSystem: 'postgresql',}) // Optional: call stop() during shutdown.Prisma only emits query events when query logging is enabled.
06 / Privacy
What gets captured,
and what doesn't.
The collector listens on loopback and requires a token for writes. Bodies, headers, cookies, query values and SQL bind parameters are dropped before anything is stored.
01 / Boundary
The short version.
Request data is redacted in your app process, then again in the collector. Only the redacted result reaches the in-memory store.
- Collector binds to 127.0.0.1 or localhost. Other hosts are rejected.
- Ingest needs a bearer token. The token file is mode 0600.
- URLs keep the path. Sensitive keys become [redacted].
- No bodies, headers, cookies, query values, fragments or SQL bind parameters.
- The store has fixed capacity and retention, and drop counters show when it fills.
- Snapshots are frozen local files. Playwright screenshots and trace archives are never stored.
- No cloud client, account, analytics or AI provider.
Loopback · token 0600 · two redaction passes
Fig 0.6Privacy
07 / FAQ
Before you
install.
Short answers about the supported stack, privacy and what StackNext leaves out.
Still deciding? The limitations page covers the supported stack, how long data is kept and known gaps.
Read limitations01Is StackNext free?
Yes. It's open source under MIT. There's no account, paid plan or hosted service.
02Does any data leave my machine?
StackNext never uploads data. The collector listens on loopback and has no cloud, analytics or telemetry endpoint. If you connect a hosted coding agent over MCP, that agent's own policy applies to what it reads.
03Which Next.js versions are supported?
Next.js 15 and 16 with the App Router on the Node.js runtime. Edge runtime and the Pages Router are not supported.
04Does it replace my existing OpenTelemetry setup?
No. StackNext uses documented Next.js telemetry, and registerStackNext() yields to an existing OpenTelemetry provider instead of starting a second SDK.
05Do I need Drizzle, Prisma or Playwright?
No. The core install is @stacknext/cli and @stacknext/next. The Drizzle, Prisma and Playwright integrations are optional.
06Is this a production APM?
No. It's a local development tool with a fixed-size sample. It has no TLS, multi-user auth or production hardening.
07Does it work with AI coding agents?
Yes. StackNext ships a read-only MCP server, so agents such as Claude Code, Codex and OpenCode can query the live sample and diagnostics. Findings still come from deterministic rules, not model output, and no AI provider is bundled.
08Can I use it in CI?
Yes, for capture and compare workflows. Comparisons are report-only unless you pass --fail-on regression, --fail-on inconclusive or --fail-on any.
08 / Start
Run it on your
next request.
Install the packages, run init, then start your app with stacknext dev. No account or API key.
terminal
npm install --save-dev @stacknext/cli @stacknext/next