Architecture Overview
Server Runtime
Rendering Pipeline
Client Navigation
Caching and Export
Development Tools
Build and Configuration
Ecosystem Packages
Testing Infrastructure
How It Works
The following files were used as context for generating this wiki page:
Next.js incorporates a unified telemetry and diagnostics subsystem designed to collect anonymous build and development usage metrics, track process memory performance, record garbage collection statistics, and persist structured build reports. This infrastructure enables the framework maintainers to prioritize feature development, track compatibility failures across platforms (such as SWC native bindings or glibc issues), and provide developers with granular diagnostics during builds and dev server lifecycles. Sources: packages/next/src/telemetry/storage.ts:51-83
The subsystem operates across several distinct operational boundaries: persistent local storage configurations managed via the conf package, detached background submission processes that prevent CLI hang on exit, V8 memory profiling triggers integrated with process signals (SIGUSR2), and trace log filters that upload selected performance spans to remote diagnostics endpoints. By decoupling event recording from synchronous network operations and gating collection behind environment variables (NEXT_TELEMETRY_DISABLED) or user opt-out preferences, the architecture balances comprehensive framework observability with strict user privacy guarantees.
Sources: packages/next/src/telemetry/storage.ts:135-154, packages/next/src/trace/upload-trace.ts:4-58
The core telemetry interface is encapsulated within the Telemetry class inside packages/next/src/telemetry/storage.ts. Upon initialization, it inspects the local execution environment to determine storage paths. Ephemeral environments such as Continuous Integration (CI) runners or Docker containers route telemetry metadata storage into the .next/cache directory, whereas standard environments utilize local configuration stores.
Sources: packages/next/src/telemetry/storage.ts:41-49
Data privacy is enforced through a one-way SHA-256 hashing mechanism that prepends a randomly generated salt (16 hex bytes) before hashing project identifiers. The storage layer maintains an asynchronous event queue implemented as a Setromise<RecordObject>>. When events are recorded, they are tracked concurrently and can either be submitted synchronously via postNextTelemetryPayload with an automatic retry wrapper or flushed via detached background worker processes.
Sources: packages/next/src/telemetry/storage.ts:113-173
import { Telemetry } from 'next/dist/client/components/react-dev-overlay/../../telemetry/storage'
// Example initialization and recording of a custom telemetry event
const telemetry = new Telemetry({ distDir: process.cwd() })
await telemetry.record({
eventName: 'NEXT_CUSTOM_EVENT',
payload: { foo: 'bar' }
})Sources: packages/next/src/telemetry/storage.ts:62-82, packages/next/src/telemetry/storage.ts:174-217
To prevent CLI commands or development servers from blocking process termination while waiting for network I/O, the telemetry storage engine implements a detached flush mechanism (flushDetached). When a development session stops or a worker exits, unsubmitted events are serialized to a process-specific temporary file (_events_id>.json) inside the distribution directory.
Sources: packages/next/src/telemetry/storage.ts:226-253
Warning
Detached flush worker processes rely on unique process IDs (_events_id>.json) to prevent race conditions between parent and child processes writing concurrently to the distribution directory.
Sources: packages/next/src/telemetry/storage.ts:244-245
The diagnostics subsystem (packages/next/src/diagnostics/build-diagnostics.ts) manages persistent JSON artifacts written to the .next/diagnostics/ directory during compilation and static generation. These files provide post-mortem debugging data when builds fail or performance degrades.
Sources: packages/next/src/diagnostics/build-diagnostics.ts:7-27
import { updateBuildDiagnostics } from 'next/dist/diagnostics/build-diagnostics'
// Updating current build stage prior to compilation steps
await updateBuildDiagnostics({
buildStage: 'bundling-webpack',
buildOptions: { target: 'server' }
})When memory debugging mode is activated via startup hooks (packages/next/src/lib/memory/startup.ts), Next.js hooks into Node.js V8 heap statistics and performance hooks to observe memory pressure and garbage collection overhead.
Sources: packages/next/src/lib/memory/startup.ts:7-51
The garbage collection observer (packages/next/src/lib/memory/gc-observer.ts) uses a PerformanceObserver listening for gc entry types. Any garbage collection cycle taking longer than LONG_RUNNING_GC_THRESHOLD_MS (15ms) triggers a warning log. Additionally, sending a SIGUSR2 signal to the Node.js process forces an on-demand V8 heap snapshot export.
Sources: packages/next/src/lib/memory/gc-observer.ts:5-27, packages/next/src/lib/memory/startup.ts:22-29
Important
Heap snapshots generated during high memory pressure will take significant time to complete and may temporarily freeze event loop execution; they are guarded by an alreadyGeneratedHeapSnapshot boolean flag to prevent cascading disk writes when heap utilization remains pegged above 70%.
Sources: packages/next/src/lib/memory/trace.ts:8-9, packages/next/src/lib/memory/trace.ts:108-117
Trace event collection and uploading are managed by packages/next/src/trace/trace-uploader.ts and packages/next/src/trace/upload-trace.ts. During development or build execution, trace spans are written to .next/trace. The uploader script reads the trace log line by line, filters events matching predefined access lists (DEV_ALLOWED_EVENTS or BUILD_ALLOWED_EVENTS), inherits parent feature flags, and posts structured payloads containing session metadata and filtered traces.
Sources: packages/next/src/trace/trace-uploader.ts:115-225, packages/next/src/trace/upload-trace.ts:4-58
Next.js embeds Model Context Protocol (MCP) servers and tracking infrastructure (packages/next/src/server/mcp/mcp-telemetry-tracker.ts) to record tool invocations during developer assistance workflows. Tool usages are accumulated in a private Map<McpToolName, number> and mapped into telemetry feature usage events upon session completion.
Sources: packages/next/src/server/mcp/mcp-telemetry-tracker.ts:1-47, packages/next/src/server/mcp/mcp-telemetry-tracker.ts:69-83
The get_page_metadata MCP tool (packages/next/src/server/mcp/tools/get-page-metadata.ts) queries active browser sessions via HMR communication channels, retrieves segment trie data, converts them into page metadata structures, and sorts them using a strict boundary precedence ordering:
Sources: packages/next/src/server/mcp/tools/get-page-metadata.ts:19-117
type === 'layout')type.startsWith('boundary:'))type === 'page')3)
Sources: packages/next/src/server/mcp/tools/get-page-metadata.ts:194-206