Configuration - StackNext

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

{
  "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.

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.