Jimmy Lai

This commit **enhances the Next.js deployment documentation** by introducing and detailing the concept of **"Verified Adapters"**. It **refactors the deployment guide** in `docs/01-app/01-getting-started/17-deploying.mdx` and `docs/01-app/02-guides/deploying-to-platforms.mdx`, categorizing platforms into "Verified Adapters" (open-source, test-suite compatible, Next.js org hosted) and "Other Platforms." This **documentation update** clarifies the Next.js team's commitments, such as coordinated testing and direct support, for these verified integrations. The change **improves user understanding** of official support levels and the ecosystem's future direction for deploying Next.js applications.

This commit significantly **enhances the Next.js documentation** to provide comprehensive guidance on **platform portability**, **infrastructure requirements**, and **CDN caching**, addressing critical feedback from platform partners. It introduces new guides covering **rendering philosophy**, **deploying to platforms**, **how revalidation works**, **CDN caching**, and a dedicated **PPR platform guide**. Existing documentation for **self-hosting**, **ISR**, **cache handlers**, and the **Adapter API** has been expanded and corrected based on thorough code verification, clarifying details like the `next-resume` header and `_N_T_` soft tags. This **documentation update** ensures greater accuracy and clarity for platform providers and developers, facilitating more robust and performant Next.js deployments across various infrastructures.

This commit **enhances the Continuous Integration (CI) pipeline** by introducing a new workflow to validate the **Node.js stream rendering path** for `app-dir` applications. It adds a new job to `.github/workflows/build_and_test.yml` that executes a curated set of existing `app-dir` tests with the `__NEXT_USE_NODE_STREAMS=true` flag enabled. A new manifest, `test/use-node-streams-tests-manifest.json`, defines which tests are run in this mode, ensuring comprehensive **test coverage** for this critical rendering mechanism. This **new capability** helps prevent regressions and guarantees the stability of Node.js stream-based rendering alongside the default web stream path.

This commit provides significant **documentation updates** to clarify the interaction between **Next.js App Router conventions**, specifically `loading.js` and `layout.js`. It addresses common confusion regarding how `loading.js` behaves when layouts are dynamic or fetch uncached data, offering explicit guidance on using `<Suspense>` for such scenarios. The **documentation improvement** includes a new "Interaction with `loading.js`" section in `layout.mdx`, a "Good to know" callout in `loading.mdx`, and consistent hierarchy clarifications across `fetching-data.mdx`, `error.mdx`, `not-found.mdx`, `page.mdx`, and `template.mdx`. This **maintenance** work enhances the developer experience by providing clearer instructions for building robust applications with dynamic layouts and data fetching.

This commit **improves the Next.js documentation** by providing clear guidance on how to properly handle **sticky headers** in applications. It addresses the common issue where Next.js's auto-scroll behavior can cause content to be obscured behind sticky elements during navigation to hash fragments or when using the `scroll` prop on the `Link` component. The update introduces `scroll-padding-top` as a recommended web-standards solution to ensure correct scroll positioning. This **documentation enhancement** helps developers build more robust and user-friendly interfaces by preventing content from being hidden behind fixed UI elements.

This commit performs a significant **refactoring** of the **Next.js App Router rendering pipeline** by extracting core functionalities into dedicated modules. It **isolates web-specific stream operations** from `app-render.tsx` into `stream-ops.web.ts` and moves the **web debug channel implementation** into `debug-channel-server.web.ts`. This improves the modularity and maintainability of the **server-side rendering (SSR)** and **streaming** logic, preparing the codebase for future platform-specific implementations. Additionally, a new `createRuntimePrefetchTransformStream` is introduced in `node-web-streams-helper.ts` to support future optimizations, and an error code is added for incorrect debug channel usage, all without altering existing runtime behavior.

This commit implements a **bug fix** to improve **dead-code elimination (DCE)** within the **`next/cache` module**, preventing server-only internals from being included in client-side browser bundles. It achieves this by **restructuring the conditional exports** in `packages/next/cache.js`, allowing bundlers to effectively tree-shake server-specific code. This change ensures that applications leveraging `next/cache` will benefit from **smaller client-side bundle sizes** and enhanced build optimization, as unnecessary server logic is no longer shipped to the browser.

This commit introduces a **performance optimization** to the **`stream-utils`** module in **Next.js**, specifically within `packages/next/src/server/stream-utils/uint8array-helpers.ts`. It **refactors** the `indexOfUint8Array` helper to utilize `Buffer.indexOf` for significantly faster byte sequence scanning in Node.js environments, falling back to a manual loop for compatibility. Additionally, the `removeFromUint8Array` function is updated to use `subarray` for improved efficiency in byte array manipulation. This **refactoring** aims to provide **faster processing of streamed data** on the server, with new unit tests added in `test/unit/stream-utils/uint8array-helpers.test.ts` to ensure the correctness of these optimized functions.

This commit introduces a comprehensive **benchmark infrastructure** to measure and analyze **render pipeline performance** and **streaming load profiles**. It includes a dedicated `bench/render-pipeline` directory with scripts for profiling render paths and analyzing CPU profiles, alongside a `bench/basic-app/app/streaming` harness featuring various stress routes (e.g., `light`, `heavy`, `chunkstorm`) to simulate diverse streaming loads. This **new capability** provides essential tooling for **performance measurement** and **analysis** of web streams versus Node streams, enabling detailed insights into rendering and data streaming efficiency. The work involves adding new scripts, components, and documentation, and updates `package.json` with new benchmark commands, all without affecting the main application's runtime behavior.

This commit introduces **significant updates to AI agent documentation and PR status tooling**. It adds **nine new agent skill documentation files** within `.agents/skills/`, covering areas like DCE, feature flags, React vendoring, runtime debugging, and PR triage, alongside guidelines for skill authoring. Furthermore, a **new `scripts/pr-status.js` script** is introduced to extract CI job environment variables and identify flaky tests, complemented by an updated `.claude/commands/pr-status.md` command and comprehensive updates to the main `AGENTS.md` development guide. This work represents a **new capability** for agent development and **enhances maintenance tooling** for CI/CD, improving the efficiency of **PR status triage and local reproduction of CI failures**.

This commit **improves the documentation** for the **`after()` function** within the **App Router API reference**, specifically clarifying the usage of **request APIs like `cookies()` and `headers()`**. It differentiates how these APIs can be used in Route Handlers/Server Functions versus Server Components, explaining that direct invocation within `after()` in Server Components will lead to runtime errors due to partial prerendering. The **documentation enhancement** provides a new code example illustrating the correct pattern for Server Components and corrects existing examples. This **clarification** helps developers avoid common pitfalls and ensures proper implementation when interacting with request data in `after()` across different Next.js environments.

This commit delivers a crucial **bug fix** for the **React Flight** server-side rendering in Node.js, specifically impacting the `renderToPipeableStream` function. It corrects an issue in the **ESM**, **Parcel**, and **Turbopack** bundler integrations where the server could incorrectly signal the availability of a debug channel. This flaw previously caused clients to **block indefinitely** when a write-only debug channel was provided, as they would wait for debug data that would never arrive. The fix ensures that debug information is only requested if a readable debug channel (`debugChannelReadable`) is explicitly available, preventing client hangs.

This commit introduces a **new experimental capability** to the **Next.js CLI**, allowing developers to capture V8 CPU profiles directly from `next dev`, `next build`, and `next start` commands using the `--experimental-cpu-prof` flag. This feature provides a first-party mechanism to diagnose performance bottlenecks in development, build, and production environments by saving detailed CPU profiles to `.next/cpu-profiles/` upon process exit. It significantly enhances the **developer experience** for performance debugging by integrating V8's profiler via the Node.js inspector, affecting the core server, build orchestration (Webpack and Turbopack), and dev server processes. Extensive **documentation** and **end-to-end tests** ensure reliable profile generation and clear naming conventions for various Next.js processes.

This commit **improves the performance statistics reporting** within the **CI/CD pipeline** by introducing **per-metric significance thresholds** that account for metric variance. It refines the logic in `.github/actions/next-stats-action/src/add-comment.js` to apply more generous thresholds for high-variance time metrics (e.g., build times) and tighter thresholds for deterministic size metrics (e.g., bundle sizes). This **maintenance and performance improvement** significantly **reduces CI noise** by preventing insignificant changes, such as minor `node_modules` size fluctuations, from being incorrectly flagged as regressions. The `formatChange`, `generateChangeSummary`, and `generateMetricsTable` functions are updated to utilize these more accurate detection criteria, ensuring only meaningful performance degradations trigger alerts.

This commit **fixes and enhances the CI/CD stats system** by enabling **historical trend tracking on canary branch pushes**. It modifies the `.github/workflows/pull_request_stats.yml` workflow to trigger on canary pushes, comparing the current canary against the last stable release and **saving these statistics to KV for long-term analysis**. This change addresses previous issues where historical data collection was either infrequent or non-functional, while also **refactoring** by removing a redundant `releaseStats` job from `build_and_deploy.yml` and renaming the workflow to `Stats` for clarity. The improved system ensures consistent metric collection, providing valuable insights into project evolution.

This commit significantly **improves the reliability and functionality of the PR stats action** by introducing **historical data persistence** via Vercel KV, enabling trend analysis and sparklines in comments. It **reduces CI noise** through new significance thresholds that filter out typical variance, ensuring only meaningful performance changes are highlighted. The **benchmarking configuration** is updated to include **dev server boot time measurements** for both Webpack and Turbopack, and the **GitHub Actions workflow** is refactored to run these benchmarks in parallel and aggregate results. This comprehensive update provides more accurate, stable, and insightful performance metrics for the project's continuous integration.

This commit introduces a comprehensive suite of **new development tooling** designed to measure, profile, and analyze the performance of the **Next.js dev server boot process** and **CLI startup**. These scripts, including `benchmark-boot-time.sh`, `benchmark-next-dev-boot.js`, `profile-next-dev-boot.js`, `analyze-profile.js`, `analyze-dev-server-bundle.js`, and `trace-cli-startup.js`, provide capabilities for wall-clock and multi-iteration benchmarking, CPU profiling, bundle analysis, and module loading tracing. This **maintenance** work empowers developers to identify and optimize performance bottlenecks, improving the overall developer experience by ensuring faster and more efficient startup times for the **Next.js development environment**.

This commit addresses **test flakiness** in the **OpenTelemetry end-to-end tests** for production mode by refining how spans are asserted. It **enhances the `expectTrace()` function** in `test/e2e/opentelemetry/instrumentation/opentelemetry.test.ts` to filter root spans based on expected `http.target` values, thereby ignoring extraneous RSC prefetch and Edge runtime boundary spans that caused assertion failures. Additionally, it **fixes a bug in the `TestExporter` callback logic** within `test/e2e/opentelemetry/instrumentation/instrumentation-test.ts` to ensure the success callback is only invoked on success. This **test maintenance** improves the reliability and accuracy of the **OpenTelemetry instrumentation testing suite**, preventing false negatives and ensuring more robust testing of Next.js's telemetry capabilities.

This commit **introduces basic configuration and comprehensive documentation for Claude Code**, an AI assistant, into the project. It adds a new `CLAUDE.md` guide detailing its use for the **Next.js development workflow**, including Git, build commands, testing, and CI analysis, alongside specific instructions for checking **CI failures** in `.claude/commands/ci-failures.md`. This **maintenance** and **documentation** effort also updates `.gitignore` and `.alexignore` to properly manage Claude-related files, enhancing the **developer experience** and integration of this new tool.

This commit introduces a significant **UI/UX enhancement** by **redesigning the default error pages** and **global error boundaries** for the App Router. It replaces the previous "White Screen of Death" with a **cleaner, more user-friendly interface** that includes **dark mode support**, unified styling, and more informative messages. Specifically, the **default 500 error page** (`AppError`) and the **global error page** (`DefaultGlobalError`) now display error digests for server errors and provide return buttons for client errors, improving user guidance. This **feature development** standardizes the visual presentation of errors across the application, ensuring a consistent and improved experience for users encountering issues.