Will Binns-Smith

This commit introduces a **new capability** by adding `experimental.serverFastRefresh` to `next.config.js`, allowing users and **Next.js plugins** to programmatically **opt out of server-side Fast Refresh**. It addresses a limitation where only a CLI flag (`--no-server-fast-refresh`) was available, which was insufficient for programmatic control. The change involves updating **configuration schemas**, refining the **server initialization logic** in `router-server.ts` to resolve the effective `serverFastRefresh` value (prioritizing CLI flags), and fixing a **Commander CLI parsing issue** by explicitly adding a hidden `--server-fast-refresh` flag. This provides more flexible control over **server-side Fast Refresh behavior** and includes warnings for conflicting CLI and config settings.

This commit **fixes a regression** in **Turbopack dev mode** where changes to **App Router metadata routes** (e.g., `manifest.ts`, `robots.ts`) were not being hot-reloaded, leading to stale content being served until a full server restart. It addresses this by **excluding metadata routes from server HMR** within the `hot-reloader-turbopack.ts` module, specifically by adding an `!isMetadataRoute(entryPage)` guard to the `usesServerHmr` expression. This ensures that metadata routes undergo full cache invalidation on every rebuild, restoring the expected development experience for these files. This **bug fix** prevents developers from encountering outdated `manifest.webmanifest` or `robots.txt` content during active development. A **new regression test** has also been added to `server-hmr.test.ts` to validate this fix.

This commit **enables server-side Hot Module Replacement (HMR)** for **App Router route handlers** when using **Turbopack** in `next dev`. It refactors the **App Router's module loading mechanism** for handlers, moving from static userland export capture to dynamic loading, similar to app pages. This **feature enhancement** allows `Turbopack` to effectively invalidate and reload route handler code by clearing the Node.js `require.cache` on rebuilds. As a result, developers will experience **instant updates to route handler logic** without requiring a full server restart, significantly improving the development workflow.

This commit **enables server HMR (Hot Module Replacement)**, also known as server fast refresh, by default for **Turbopack-powered app router pages**, significantly improving the **developer experience** with faster feedback loops. It **removes the experimental flag** `--experimental-server-fast-refresh`, replacing it with a new opt-out flag, `--no-server-fast-refresh`, and updates **telemetry** to record when the feature is disabled. This **feature enablement** and **configuration change** involves **refactoring** option names across the **Next.js CLI**, the **Turbopack hot reloader** (`hot-reloader-turbopack.ts`), and various **server-side initialization components** (`router-server.ts`, `start-server.ts`). The change streamlines development for app router users, though server HMR remains disabled for routes and middleware.

This commit introduces a **new capability** for **Turbopack** production builds, generating detailed **route bundle stats** in a machine-readable JSON format. After a successful build, a file named `.next/diagnostics/route-bundle-stats.json` is created, containing **first-load JavaScript bytes** and associated chunk paths for each route. This enhancement provides more accurate and actionable **diagnostics** for developers to monitor and optimize initial page load performance, replacing previous, less reliable stdout-based reporting with a structured output. The change primarily affects the **Turbopack build process** and **developer tooling** for performance analysis.

This commit introduces a **new feature** to the **bundle analyzer**, enabling a more comprehensive visualization of route-specific bundles. It now **merges shared modules from `_app` and `_document` into the current route's analysis data**, ensuring that common dependencies are accurately represented in the treemap. This is implemented by adding a `combine_output_assets` function in `crates/next-api/src/analyze.rs` and modifying `get_analyze_data_operation` in `crates/next-napi-bindings/src/next_api/analyze.rs` to perform this data integration. Consequently, developers gain a more complete and realistic understanding of a route's total bundle size, facilitating better optimization decisions, and ensuring compatibility with App Router projects.

This commit introduces a **new capability** to the **Next.js tracing subsystem**, enabling spans to be explicitly marked as failed. A dedicated `failed` attribute is now added to tracing spans, which is set to `true` if the function wrapped by `traceFn` or `traceAsyncFn` throws an error. This enhancement significantly improves the observability and debugging experience by providing clear, semantic failure indications directly within trace data. The functionality is validated with **new end-to-end tests** that specifically confirm `next-build` spans are correctly tagged as failed when a build process encounters an error.

This commit **enhances the trace upload mechanism** by incorporating crucial **Git and Vercel environment information** into the uploaded trace metadata. It now includes the Git branch/ref name and a flag indicating if the trace originated from a Vercel environment, with a preference for Vercel-specific environment variables for Git data. This **new capability**, implemented within `packages/next/src/trace/trace-uploader.ts` via the `uploadTraces` function, provides richer context for **telemetry and diagnostic data**. This improvement significantly aids in understanding the origin and environment of uploaded traces, thereby improving overall debuggability.

This commit **refactors** the internal mechanism for propagating **Hot Module Replacement (HMR)** enablement within **Turbopack's ECMAScript analysis** pipeline. The `is_hot_module_replacement_enabled` flag is now directly passed from `CompileTimeInfo` to the `ImportMetaBinding` constructor, replacing its previous derivation from `ChunkingContexts`. This change impacts the `turbopack-ecmascript` crate, specifically modifying `turbopack/crates/turbopack-ecmascript/src/references/esm/meta.rs` to include an `hmr_enabled` field in `ImportMetaBinding` and utilize it during `code_generation`. The `analyze_ecmascript_module_internal` function in `turbopack/crates/turbopack-ecmascript/src/references/mod.rs` is updated to facilitate this new data flow, ensuring accurate HMR behavior for `import.meta` expressions during compilation.

This commit **refines the Turbopack server-side Hot Module Replacement (HMR) mechanism** by **restricting its application exclusively to App Router pages**. It addresses a limitation where server HMR was incorrectly attempting to apply to other App Router types, such as **route handlers**, which bypass the Turbopack runtime and are not easily supported. This **maintenance fix**, implemented within `createHotReloaderTurbopack`, prevents potential issues and ensures more stable development experiences for **Next.js App Router** users leveraging Turbopack. New **e2e tests** were added to validate this specific behavior, confirming that route handlers are now correctly excluded from server HMR.

This commit **enhances the debugging experience** for **Turbopack server HMR** by **preserving accurate stack frame information** for `eval`ed modules. Previously, stack traces were lost, hindering effective debugging of server-side code during development. The **Turbopack Node.js HMR runtime** now appends `//# sourceURL` and base64-encoded `//# sourceMappingURL` to each `eval`ed module entry, ensuring stack frames correctly point to original source locations. This **bug fix and feature enhancement** significantly improves the accuracy of error reporting and the overall debugging workflow within the **Turbopack development environment**, with new tests added to verify the correct behavior of server HMR source maps.

This commit introduces a **new capability** by implementing a `restart` event for **Turbopack server HMR**, which is crucial for fully evicting all caches when client manifest changes occur. This enhancement primarily affects the **hot-reloader-turbopack.ts** module, where the `setupServerHmr` and `createHotReloaderTurbopack` functions are updated to handle this event and **refactor** existing cache clearing logic. The `restart` event ensures that client manifest changes reliably trigger a full cache invalidation, significantly improving the development experience for **Next.js** applications using Turbopack. An associated test in `dev-fetch-hmr.test.ts` was also updated to ensure reliable HMR triggering.

This commit delivers a crucial **bug fix** for **Turbopack's experimental server HMR**, primarily addressing issues where **Pages Router updates were not correctly reflected** during development. It resolves several caching problems within `hot-reloader-turbopack.ts`, ensuring **Pages Router pages clear the chunk cache**, enabling `deleteCache` for server HMR subscriptions to prevent "Could not find module" errors, and explicitly calling `clearModuleContext` for **middleware and edge routes**. Furthermore, the **chunk cache is now cleared for `.env` and configuration changes**, significantly improving the reliability and correctness of Hot Module Replacement across various Next.js routing and runtime environments when using Turbopack.

This commit provides a **bug fix** for the **Turbopack HMR (Hot Module Replacement) runtime**, specifically addressing an issue within the `installCompressedModuleFactories` function in `turbopack-ecmascript-runtime`. Previously, this function would erroneously skip installing module factories for an entire group of module IDs if any single ID within that group was already registered. The **refactoring** ensures that factories are now correctly installed for each individual module ID, preventing modules from being missed during HMR updates. This improves the **reliability of Hot Module Replacement** for **Turbopack users**, ensuring consistent application state during development.

This commit introduces a **new capability** to the **trace upload system** by including the states of enabled experimental flags in trace events. It modifies the `next build` and `next dev` CLI commands to collect these flags and the server startup logic to apply them, ensuring they are propagated and denormalized onto every descendent span within the trace. The `trace-uploader.ts` module is updated to handle this new data, providing crucial context for debugging and analyzing applications utilizing experimental features when `--experimental-trace-upload` is active. This enhancement improves observability by linking trace data directly to the experimental configurations under which the application is running.

This commit fully implements **Server-Side Hot Module Replacement (HMR)** within **Turbopack's Node.js development runtime**, completing the necessary functionality for **Fast Refresh** in **React Server Components (RSC)**. It introduces a dedicated **Node.js HMR client** (`hmr-client.ts`) and integrates it with the existing Turbopack update system, allowing only modified modules to be re-evaluated while preserving the state of unaffected ones. This significant **new feature** enhances the **developer experience** by providing faster, more granular updates during development. The implementation involves updates across **Turbopack's Rust core** for payload generation, **Turbopack's JavaScript runtime** for client-side logic, and the **Next.js hot-reloader** (`hot-reloader-turbopack.ts`) for integration, all validated by comprehensive new end-to-end tests.

This commit performs a significant **refactoring** of **Turbopack's Hot Module Replacement (HMR) client logic**, extracting its core functionality into a new shared runtime file, `hmr-runtime.ts`. This architectural improvement abstracts away platform-specific details like websocket transport and page reload, making the HMR core reusable. The **browser development runtime** within `turbopack-ecmascript-runtime` is updated to utilize this new shared logic, adapting functions like `instantiateModule` and `applyEcmascriptMergedUpdate`. This change introduces a **new shared capability** and lays the groundwork for future implementation of an in-process backend for **Node.js server HMR**.

This commit **reorganizes runtime files** within the **Turbopack Ecmascript runtime**, specifically moving non-module system JavaScript code concatenated by Rust into a new `shared/runtime` directory. This **refactoring** improves the clarity and organization of runtime components for both browser and Node.js environments, updating all internal TypeScript and Rust references. It also **establishes a new convention** for runtime file placement, documented in `turbopack/crates/turbopack-ecmascript-runtime/js/README.md` and `AGENTS.md`, to ensure future consistency and prevent confusion with other code. This is purely a **code movement** and **maintenance** task, with no functional changes, ensuring downstream stability.

This commit introduces the foundational **server-side Hot Module Replacement (HMR) infrastructure** for Turbopack within Next.js, enabling future capabilities for applying server-side code changes without a full server restart. It **refactors** the existing HMR system by renaming client-specific code and introducing new APIs, such as `project.serverHmrEvents()`, to support distinct server HMR event subscriptions. This **new capability** impacts the **Turbopack integration** and **developer experience** by laying the groundwork for faster iteration on server-side logic, including a stub for the `__turbopack_server_hmr_apply__` runtime function. The changes span across `next-api`, `next-napi-bindings`, and Next.js server-side modules, preparing the system for comprehensive server HMR.

This commit introduces a **new tracing capability** to record `render-path` times for requests within the **Next.js development server**. Analogous to `compile-path`, this **new feature** provides more granular performance data, allowing developers to see the render duration for each route directly in trace files and aligning with the CLI output. It involves modifications to the **server request handling** (`next-dev-server.ts`) and the **tracing infrastructure** (`trace-uploader.ts`), including a new utility `hrtimeToEpochNanoseconds`. This enhancement improves **observability** for developers by providing detailed insights into request processing times. Additionally, comprehensive **new tests** are added to verify the recording of HMR data within these traces.