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

# Installation

> Install StackNext in a Next.js App Router project, initialize it, verify the collector and remove it safely.

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

| Requirement | Supported |
| - | - |
| Framework | Next.js 15 or 16, App Router only |
| Runtime | Node.js runtime. Edge runtime is not supported |
| Node.js | 20.9 or newer |
| Package manager | npm and pnpm are validated; yarn and bun work with the same commands |
| Database adapters | Optional: Drizzle or Prisma |
| Playwright | Optional: only for captured regression scenarios |

`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](https://docs.stacknext.space/compatibility.md) 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:

```bash theme={null}
npm install @stacknext/next
npm install --save-dev @stacknext/cli
```

pnpm:

```bash theme={null}
pnpm add @stacknext/next
pnpm add -D @stacknext/cli
```

yarn:

```bash theme={null}
yarn add @stacknext/next
yarn add -D @stacknext/cli
```

bun:

```bash theme={null}
bun add @stacknext/next
bun add -d @stacknext/cli
```

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

| Package | Purpose |
| - | - |
| `@stacknext/drizzle` | Drizzle query logger. `drizzle-orm` is an optional peer |
| `@stacknext/prisma` | Prisma query event adapter. `@prisma/client` is an optional peer |
| `@stacknext/playwright` | Playwright fixtures for runtime regression capture. `@playwright/test` is an optional peer |

## Initialize the project

```bash theme={null}
npx stacknext init
```

With pnpm:

```bash theme={null}
pnpm exec stacknext init
```

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

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

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

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

If `onRequestError` already exists, call `stackNextOnRequestError(error,
request, context)` inside it. StackNext yields to an existing OpenTelemetry
tracer provider instead of replacing it.

> [!WARNING]
>
> 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

```bash theme={null}
npx stacknext dev
```

Or with pnpm:

```bash theme={null}
pnpm exec stacknext dev
```

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

> [!NOTE]
>
> `.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:

```bash theme={null}
npx stacknext status
npx stacknext doctor
npx stacknext coverage
npx stacknext diagnose
```

`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

* [Connect a database integration](https://docs.stacknext.space/integrations/database.md).
* [Add custom spans](https://docs.stacknext.space/custom-instrumentation.md).
* [Review the configuration reference](https://docs.stacknext.space/reference/configuration.md).
* [Connect an AI coding agent](https://docs.stacknext.space/ai-agents/setup.md).

## 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](https://github.com/marrrkkk/stacknext/blob/main/CHANGELOG.md)
   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:

```bash theme={null}
pnpm --filter ./apps/my-app add @stacknext/next
pnpm --filter ./apps/my-app add -D @stacknext/cli
pnpm --filter ./apps/my-app exec stacknext init
pnpm --filter ./apps/my-app exec stacknext dev
```

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

```bash theme={null}
npx stacknext uninstall
```

Apply the safe cleanup:

```bash theme={null}
npx stacknext uninstall --yes
```

| Option | Effect |
| - | - |
| `--yes` | Apply the planned removals. Without it the command is a dry run |
| `--keep-config` | Preserve `stacknext.config.json` |
| `--remove-data` | Also remove saved runs, baselines and comparisons |
| `--json` | Print a machine-readable plan or result |

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:

```bash theme={null}
pnpm remove @stacknext/cli @stacknext/next
```

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.


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