Next.js Project Guide

Complete rollout pattern for Next.js apps (Node runtime + browser telemetry)

Use this guide when your product surface is Next.js and you need end-to-end visibility across server and browser paths.

Architecture Scope

  • Server runtime: API routes, server actions, SSR logic.
  • Browser runtime: user interactions, route transitions, frontend errors.
  • Shared context: service/env/version/release IDs for correlation.
  1. Configure environment-scoped credentials.
  2. Initialize Node SDK on server startup paths.
  3. Initialize Browser SDK on client bootstrap.
  4. Capture request boundaries, external calls, and error paths.
  5. Attach release metadata from CI/CD.

Minimum Data Contract

Emit and standardize:

  • service: web-nextjs
  • env: dev / staging / prod
  • version: commit SHA or build ID
  • Request identifiers for server/client correlation

Validation Checklist

  • Browser and server events are both visible.
  • Server errors include request context.
  • Frontend incidents can be mapped to backend traces.
  • Deploy events are visible in incident timeline.

Production Hardening

  1. Keep server keys private; only use public keys in browser where required.
  2. Configure replay/sampling to control cost.
  3. Ensure graceful shutdown flush for server runtime.
  4. Validate instrumentation after each framework upgrade.

Troubleshooting

  • Missing client data: verify client bootstrap executes once.
  • Missing server data: verify SDK initialization in server runtime path.
  • Broken correlation: standardize version/release fields.

On this page