Jiwon Choi

This commit **updates the documentation** for the **App Router**, specifically enhancing the explanation of `unstable_catchError`. It adds a new section to `docs/01-app/03-api-reference/04-functions/catchError.mdx` that details the key advantages of using `unstable_catchError` over traditional React error boundaries. The **documentation update** clarifies that `unstable_catchError` provides built-in error recovery via `retry()`, framework-aware handling of `redirect()` and `notFound()` functions, and automatic error state clearing during client-side navigation. This helps developers understand the advanced error handling capabilities and improved integration offered by this API within the framework.

This commit significantly **improves the clarity and consistency of the Next.js App Router error handling documentation**. It **standardizes the usage of the `ErrorInfo` type** in `catchError.mdx` examples, replacing inline types and consolidating imports for better readability. Additionally, this **documentation maintenance** updates all examples to directly use `unstable_retry` instead of an alias across `error-handling.mdx` and `catchError.mdx`, and refines error boundary descriptions to consistently use "children" instead of "contents" in `catchError.mdx` and `error.mdx`. These changes ensure that users encounter accurate and uniform code patterns and terminology when learning about error recovery.

This commit **optimizes CI performance** by classifying changes within the `.agents`, `.claude`, and `.cursor` directories as documentation-only. It modifies the `CHANGE_ITEM_GROUPS` configuration in `scripts/run-for-change.mjs` to include these paths in the `docs` group. Consequently, the `build_and_deploy.yml` and `build_and_test.yml` CI workflows will now **skip unnecessary builds and tests** when only these agent skill definitions or editor configurations are altered. This **maintenance** change reduces CI run times and resource consumption by avoiding irrelevant checks.

This commit introduces a **configuration update** by adding a symbolic link, `.claude/skills`, which points to `../.agents/skills`. This **maintenance chore** is specifically designed to enhance the **skill discovery mechanism** within the `.claude` environment. By establishing this alias, the system can now seamlessly locate and utilize skills defined in the `../.agents/skills` directory. This change streamlines skill management and ensures proper integration of agent-defined skills into the Claude system, improving overall functionality.

This commit **temporarily skips** the `unstable_catchError with react compiler` end-to-end test located in `test/e2e/app-dir/catch-error/catch-error-react-compiler.test.ts`. This **maintenance fix** is implemented to **unblock the CI pipeline**, which was failing due to a newly discovered **compatibility issue** between Next.js's Pages directory, React 17/18, and the React compiler. By conditionally disabling this test when React version is 18, the project's continuous integration can proceed while the root cause of the incompatibility is investigated in parallel. This ensures that other development and releases are not halted by this specific test failure. The **`unstable_catchError` feature** and its interaction with the **React compiler** are the primary subsystems affected by this temporary workaround.

This commit provides **new documentation** for the `unstable_catchError()` function, a **new capability** designed for **component-level error recovery** within the Next.js App Router. It introduces a dedicated API reference file, `catchError.mdx`, detailing its parameters, returns, and usage examples. Additionally, the general error handling guide (`error-handling.mdx`) is updated with a new section and code examples, and a note is added to the `error.mdx` file convention documentation. This comprehensive **documentation** effort aims to improve developer understanding and adoption of **fine-grained error handling** strategies in Next.js applications.

This commit **improves the comprehensiveness of error messages** related to **React Server Components (RSC)** usage within Next.js. It updates the expected error outputs for various Next.js features like `cacheLife`, `cacheTag`, `next/root-params`, `server-only`, and `after()`, as well as specific React and ReactDOM API hooks, when they are misused in either **App Router** or **Pages Router** contexts. This **developer experience improvement** ensures that users receive clearer feedback, aiding in debugging and correct implementation of RSC patterns. The changes primarily involve **refactoring** existing error messages and updating corresponding test snapshots across the `next-custom-transforms` crate and acceptance tests.

This commit **fixes a TypeScript type inference bug** affecting the **`unstable_catchError` component** within **Next.js client components**. Previously, TypeScript failed to correctly infer generic props `P` for the fallback function's parameters, leading to type errors about missing properties when defining the fallback component. The **type definitions for `unstable_catchError` and its `Fallback` component** have been adjusted to resolve this issue. This **bug fix** improves type safety and developer experience, ensuring that users can correctly define and use fallback components with `unstable_catchError` without encountering erroneous TypeScript errors.

This commit introduces the **new `unstable_catchError()` API**, providing a **granular custom error boundary** for Next.js applications. This **new capability** allows developers to define specific error handling components with reset and retry functionalities, significantly enhancing the **error recovery experience** across both the **App Router** and **Pages Router**. The API is exported from `next/error` and includes specific safeguards to prevent its misuse in **React Server Components**, while `unstable_retry()` is explicitly disallowed in the Pages Router due to its dependency on `router.refresh()`. This **feature** offers a more flexible and powerful way to manage runtime errors, improving application resilience.

This commit performs a significant **refactoring** to **remove the legacy "PPR postpone cluster"** and its associated dynamic rendering mechanism. It **removes the `isDynamicPostpone` checks** from the `unstable_rethrow` function in client components and the `isDynamicUsageError` function in export helpers. Crucially, the commit **deletes the `Postpone` class and related helper functions** such as `postponeWithTracking` and `isDynamicPostpone` from the server-side app renderer. This cleanup effort streamlines the **Partial Prerendering (PPR) implementation** by eliminating a deprecated or superseded feature, simplifying the codebase and improving maintainability.

This commit performs a **maintenance refactoring** by **migrating test fixtures** from the deprecated `experimental.ppr` configuration to the new `cacheComponents` setting. It updates `next.config.js` files within the **test environments** to enable `cacheComponents` and removes `experimental_ppr` exports from test components. Furthermore, several **test components** in the `metadata-streaming-config` suite are refactored to use `Suspense` and `DynamicContent`, aligning them with the new **Partial Prerendering (PPR)** approach. This ensures the **e2e and production test suites** remain compatible and accurate with the latest Next.js features.

This commit **removes the `PrerenderStorePPR` type and all associated `prerender-ppr` case handling** from the Next.js codebase. This **refactoring** effort streamlines the **server-side rendering and request handling logic** by eliminating a specific, likely deprecated, prerendering strategy. Affected areas span **dynamic rendering, work unit storage, request parameter creation (pathname, root params, search params), cache management, and revalidation functions**. The removal simplifies the codebase by excising dedicated logic for `prerender-ppr`, indicating this mechanism is no longer supported or required.

This commit **refactors** the **App Router rendering pipeline** by removing the deprecated `isRoutePPREnabled` flag and its associated experimental Partial Prerendering (PPR) logic. It replaces checks for PPR enablement with `cacheComponents` or `isCacheComponentsEnabled` across several core rendering functions, including `renderToHTMLOrFlight` and `createComponentTreeInternal`. This change **cleans up dead code** and simplifies the internal handling of component caching, affecting how app pages are rendered and exported. The `experimental.isRoutePPREnabled` property is also removed from the `WorkStoreContext` type definition, streamlining the internal state management.

This commit performs a significant **refactoring** and **maintenance** task by replacing all internal checks for the deprecated `experimental.ppr` configuration with the new `cacheComponents` flag, which controls Partial Prerendering (PPR) behavior. It updates core modules such as the **client-side router reducer** (`fetchServerResponse`), **server-side request handling** (`base-server.ts`), **export process** (`exportAppImpl`), and **static path generation** to consistently use `cacheComponents`. This change standardizes how PPR is enabled and checked across the framework, deprecating the old experimental flag in `config-shared.ts` and simplifying the internal logic by removing legacy configuration checks. The update ensures uniform management of PPR enablement and prepares the system for future enhancements.

This commit **updates the documentation** for **error handling** within the **App Router** to reflect a recent API change. It replaces all references to the deprecated `reset()` function with the new `unstable_retry()` function in code examples and explanations. Specifically, the `error-handling.mdx` and `error.mdx` files are updated to guide developers towards using `unstable_retry()` as the **preferred retry mechanism** for error components. This **documentation update** ensures users are informed about the latest and recommended approach for handling errors.

This commit **optimizes** the **`next-stats-action` GitHub Action** by changing how tarball URLs are generated for **PR stats comments**. Previously, the action would unnecessarily query the GitHub API to resolve the commit SHA from a PR number, wasting resources. Now, the `generatePrTarballSection` function in `.github/actions/next-stats-action/src/add-comment.js` directly uses the commit SHA, which is made available via a new `githubHeadSha` property added to the `actionInfo` object in `.github/actions/next-stats-action/src/prepare/action-info.js`. This **performance enhancement** significantly **reduces GitHub API calls** and improves the efficiency of the CI/CD pipeline when generating pull request statistics.

This commit introduces the **`unstable_retry()` prop** to the **Next.js error components API**, significantly **enhancing error recovery capabilities**. This **new capability** provides built-in retry logic for errors originating from data fetching or React Server Components, by internally invoking `router.refresh()` and `reset()` within a `startTransition()`. It offers a more comprehensive solution than the existing `reset()` prop, which only clears error state, and is expected to become the preferred method for most recovery scenarios. This **improves the developer experience** by simplifying the implementation of robust error handling in **Next.js applications**.

This commit **introduces the `reset()` function** to the user's **`global-error.js` component**, enabling developers to programmatically clear error states from their global error pages. This **new capability** ensures `global-error.js` has the same options as `error.js` and **synchronizes development environment behavior with production**, where this functionality was already available. The change involves **updating type definitions** for `GlobalErrorComponent` and `ErrorComponent` in `packages/next/src/client/components/builtin/global-error.tsx` and `packages/next/src/client/components/error-boundary.tsx`, respectively. Additionally, the `AppDevOverlayErrorBoundary` in `packages/next/src/next-devtools/userspace/app/app-dev-overlay-error-boundary.tsx` is updated to pass this `reset` method, enhancing error recovery mechanisms and preparing for future features like `retry()`.

This commit **updates the documentation** for **agents testing** by replacing the outdated `testonly` command with `testheadless` in `AGENTS.md`. This **maintenance** change clarifies the correct procedure for running tests in a **headless environment**, preventing browsers from launching during the testing process. The update also explicitly mentions the use of `NEXT_TEST_MODE` for configuring test execution. This ensures developers can efficiently run agent tests without GUI interference, improving the testing workflow.

This commit introduces a **validation check** within the **Next.js core configuration parsing** to prevent the `unstable_instant` route segment option from being used in **Client Components**. Since `unstable_instant` relies on prefetching, which Client Components do not participate in, this change ensures semantic correctness and prevents potential misconfigurations. It **enhances error handling** by throwing a specific error when this misuse is detected, with new error messages added to `errors.json`. This **prevents incorrect usage patterns** and guides developers towards proper application of route segment options.