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

# Configuration

> stacknext.config.json fields, defaults and the environment variables stacknext dev sets.

StackNext reads `stacknext.config.json` from the project directory when
`stacknext dev` starts. `stacknext init` creates it with mode `0600` when it is
missing. The file is optional: a project without it uses the defaults.

## Example

```json theme={null}
{
  "projectName": "my-app",
  "dashboard": { "port": 4400 },
  "collector": { "maxSpans": 5000, "retentionMs": 600000 },
  "instrumentation": {
    "verbose": false,
    "captureFetch": true,
    "captureErrors": true
  },
  "privacy": {
    "captureHeaders": false,
    "captureRequestBodies": false,
    "captureSqlParameters": false,
    "redactSensitiveData": true
  },
  "database": { "drizzle": false, "prisma": false },
  "diagnostics": {
    "enabled": true,
    "repeatedQueryMin": 5,
    "slowSpans": {
      "databaseMs": 250,
      "httpMs": 500,
      "customMs": 300,
      "frameworkMs": 500,
      "otherMs": 500
    },
    "repeatedHttpMin": 3,
    "errorGrouping": true,
    "errorGroupMin": 2,
    "maxFindings": 100
  },
  "slowRequestMs": 500,
  "snapshots": {
    "autoOnExit": true,
    "autoOnError": true,
    "autoKeep": 10,
    "maxBytes": 67108864
  }
}
```

## Fields

| Field | Default | Meaning |
| - | - | - |
| `projectName` | App package name | Project name reported to the collector |
| `dashboard.port` | `4400` | Preferred loopback dashboard port. StackNext tries the next 25 ports if it is busy |
| `collector.maxSpans` | `5000` | In-memory span capacity. Error and query buffers are derived from it |
| `collector.retentionMs` | `600000` | How long received telemetry stays in memory (10 minutes) |
| `instrumentation.verbose` | `false` | Enables the documented `NEXT_OTEL_VERBOSE=1` Next.js span set |
| `instrumentation.captureFetch` | `true` | Captures Next.js `AppRender.fetch` spans. Set `false` to drop them |
| `instrumentation.captureErrors` | `true` | Calls the Next.js error hook. Set `false` to disable error collection |
| `privacy.captureHeaders` | `false` | Must stay `false`; StackNext rejects header capture |
| `privacy.captureRequestBodies` | `false` | Must stay `false`; StackNext rejects body capture |
| `privacy.captureSqlParameters` | `false` | Must stay `false`; StackNext never reads bind parameters |
| `privacy.redactSensitiveData` | `true` | Must stay `true`; any other value is rejected at config load |
| `database.drizzle` | `false` | Setup hint for `init`, `doctor` and coverage. Does not register the logger |
| `database.prisma` | `false` | Setup hint for `init`, `doctor` and coverage. Does not attach the event handler |
| `diagnostics.enabled` | `true` | Enables the deterministic report and its API, CLI, dashboard and MCP surfaces |
| `diagnostics.repeatedQueryMin` | `5` | Minimum repeated normalized queries in one trace for `n-plus-one-queries` (2–100) |
| `diagnostics.slowSpans.databaseMs` | `250` | Slow-span threshold for database spans |
| `diagnostics.slowSpans.httpMs` | `500` | Slow-span threshold for HTTP spans |
| `diagnostics.slowSpans.customMs` | `300` | Slow-span threshold for custom application spans |
| `diagnostics.slowSpans.frameworkMs` | `500` | Slow-span threshold for framework spans |
| `diagnostics.slowSpans.otherMs` | `500` | Slow-span threshold for other spans |
| `diagnostics.repeatedHttpMin` | `3` | Minimum repeated normalized HTTP endpoints in one trace for `repeated-external-http` |
| `diagnostics.errorGrouping` | `true` | Enables error fingerprint grouping |
| `diagnostics.errorGroupMin` | `2` | Occurrence count used to label an error finding as repeated. A single observed error is still reported |
| `diagnostics.maxFindings` | `100` | Hard cap on findings in one report (10–1,000) |
| `slowRequestMs` | `500` | Threshold used by the dashboard, CLI and MCP slow-request views |
| `snapshots.autoOnExit` | `true` | Save a snapshot when `stacknext dev` exits gracefully and the sample has data |
| `snapshots.autoOnError` | `true` | Save a snapshot on the first error, with a 60-second cooldown |
| `snapshots.autoKeep` | `10` | Number of automatic exit/error snapshots to keep (1–100) |
| `snapshots.maxBytes` | `67108864` | Per-snapshot size cap (1 MiB–256 MiB). Oversized saves fail rather than truncate |

The config is validated with Zod. Invalid values and unknown fields are rejected
at startup.

## Environment variables

`stacknext dev` sets these for the Next.js child process. The app's
`instrumentation.ts` does not read the config file directly.

| Variable | Purpose |
| - | - |
| `STACKNEXT_COLLECTOR_URL` | Loopback collector endpoint |
| `STACKNEXT_TOKEN` | Ingestion bearer token |
| `STACKNEXT_PROJECT_NAME` | Project name reported to the collector |
| `STACKNEXT_CAPTURE_FETCH` | `0` or `1` for fetch span capture |
| `STACKNEXT_CAPTURE_ERRORS` | `0` or `1` for the error hook |
| `STACKNEXT_DEBUG` | Collector transport debug logging |
| `NEXT_OTEL_VERBOSE` | Documented Next.js verbose span switch |

An explicit inherited `NEXT_OTEL_VERBOSE` wins over
`instrumentation.verbose`, including `NEXT_OTEL_VERBOSE=0`. Next.js treats only
the literal value `1` as enabled. Verbose tracing adds spans and overhead; see
[instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md#verbose-tracing).

## Privacy fields

StackNext refuses to enable headers, bodies or SQL parameters. Those fields must
stay `false`; they exist so the boundary is explicit and validated. See
[privacy](https://docs.stacknext.space/privacy.md).

## Related

* [Database integrations](https://docs.stacknext.space/integrations/database.md)
* [Instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md)
* [Snapshots](https://docs.stacknext.space/guides/snapshots.md)
* [CLI commands](https://docs.stacknext.space/cli/commands.md)


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