Skip to main content
StackNext is installed into the Next.js application you want to inspect. It does not require an account, a hosted service or an AI provider.

​
Requirements

stacknext init rejects a missing app/ or src/app/ directory and a Next.js major below 15. A newer major prints a warning because it is outside the tested range. See compatibility for the recorded matrix. Install inside the application directory, not in a parent folder. The collector and dashboard use http://127.0.0.1:4400 by default and try the next 25 loopback ports when it is busy.

​
Install the packages

npm:
pnpm:
yarn:
bun:
@stacknext/cli contains the CLI, collector and dashboard. @stacknext/next is the instrumentation and OpenTelemetry exporter loaded by your app, so install it as a production dependency. Keep the CLI as a development dependency. The collector, dashboard, diagnostics, regression and MCP packages are installed automatically as dependencies of the CLI. Add these only when you use the integration:

​
Initialize the project

With pnpm:
init performs these checks and writes only what is missing:
  1. It finds package.json, the Next.js version and app/ or src/app/.
  2. It creates stacknext.config.json with private (0600) permissions.
  3. It creates instrumentation.ts for a TypeScript project, or instrumentation.js for a JavaScript project.
  4. It detects Drizzle and Prisma and prints the adapter setup.
  5. It reports whether @stacknext/next is declared. Pass --install to let the detected package manager install it.
  6. It can add managed AI-agent instructions with --agents.
init is idempotent. Running it again leaves valid files unchanged.

​
Existing instrumentation is never overwritten

If the project already has an instrumentation file, init leaves it untouched. Add the hook yourself:
If onRequestError already exists, call stackNextOnRequestError(error, request, context) inside it. StackNext yields to an existing OpenTelemetry tracer provider instead of replacing it.
Never replace a registration that already starts monitoring. Add registerStackNext() inside the existing register() so StackNext yields to the current OpenTelemetry provider instead of starting a second one.
The generated hook checks NEXT_RUNTIME === 'nodejs' and imports StackNext dynamically. Edge compilation must not load the Node.js transport.

​
Start the collector and app

Or with pnpm:
dev starts the loopback collector, writes .stacknext/run.json with mode 0600, and runs your app’s own dev script with the collector URL and token in its environment. The dashboard URL is printed at startup and is usually http://127.0.0.1:4400. Use --open to open it in the default browser.
.stacknext/run.json holds a short-lived bearer token and must stay private. Never commit it, paste it into an issue or copy it into another app.
Make a request to your app. The dashboard reflects a bounded in-memory sample; it does not show historical data from a previous run.

​
Verify the installation

With stacknext dev running in another terminal:
doctor is the first stop when the dashboard is empty. coverage describes only what the current retention window observed; it is not a health score.

​
Next steps

​
Upgrade

  1. Stop stacknext dev with SIGINT or SIGTERM.
  2. Install the new versions with the same package manager.
  3. Run stacknext init again. It preserves user-owned files and validates the existing config.
  4. Run stacknext doctor, then stacknext dev.
  5. Review the changelog for behavior changes.
Upgrading packages does not delete .stacknext/runs, .stacknext/baselines or .stacknext/comparisons. Those records are versioned and kept until you remove them explicitly.

​
Workspaces and monorepos

Install StackNext in the Next.js application package, not at the workspace root, so the CLI can find that app’s package.json, dev script and Next.js version. In a pnpm workspace:

​
Remove StackNext

stacknext uninstall removes only files that StackNext generated. It does not delete user-authored instrumentation, application data or saved records unless you ask for it. Stop stacknext dev with SIGINT or SIGTERM first and wait for it to exit. Uninstall refuses to remove runtime files while the recorded process is alive. Preview the removals (the default is a dry run):
Apply the safe cleanup:
The command leaves an instrumentation file you edited or wrote yourself, application code, node_modules, lockfiles and .stacknext capture data alone unless --remove-data is passed. Remove the packages with your package manager. For pnpm:
Remove @stacknext/drizzle, @stacknext/prisma or @stacknext/playwright only if you installed them. The other @stacknext/* packages are dependencies of the CLI and disappear with it. If the CLI is no longer available, delete stacknext.config.json if StackNext created it, remove the StackNext import and hook from your instrumentation file, and delete .stacknext/run.json. Keep .stacknext/runs, .stacknext/baselines and .stacknext/comparisons if you still need the evidence. Also remove the MCP server entry and the stacknext-debugging skill from your agent configuration.