Joseph

This commit provides **documentation improvements** for the **Open Graph image configuration** within the Next.js App Router API reference. It addresses minor "papercuts" by correcting a grammatical error regarding the possessive 'its' in the `opengraph-image.mdx` file. Additionally, the commit updates an HTML meta tag example, changing the attribute from `property="twitter:image:alt"` to the more appropriate `name="twitter:image:alt"`. This **maintenance** work ensures the documentation is accurate and provides correct examples for developers implementing social media metadata.

This commit delivers **documentation fixes and improvements** across several sections of the **Next.js `app` directory documentation** following a recent release. It addresses various inaccuracies in code examples, including correcting filenames, resolving syntax errors like missing braces, and updating function names and type definitions in guides for layouts, linking, revalidation, error handling, and CSS. Additionally, the commit refines code highlighting for `updateTag` and `unstable_catchError` usage and introduces a new section detailing instructions for earlier versions of AI agents. This **maintenance work** ensures the documentation is accurate and provides correct guidance for developers.

This commit **improves the documentation** for the **Next.js TypeScript configuration**, specifically clarifying the behavior of the `ignoreBuildErrors` option. A note has been added to the `typescript.mdx` file, explaining that this setting causes the build process to **completely skip type checking** rather than merely suppressing type errors. This **documentation update** ensures developers have a more accurate understanding of how `ignoreBuildErrors` impacts their project's build integrity and type safety. The change provides crucial context for users configuring their Next.js applications with TypeScript.

This commit introduces a **new, comprehensive guide** for **Next.js streaming**, detailing its functionality, best practices, and implementation considerations within the `docs/01-app/02-guides/streaming.mdx` file. This **documentation enhancement** provides developers with in-depth information on how to effectively use and understand streaming, including when and how to block it, and its relation to performance metrics like INP. Additionally, it **updates internal links** in related guides like `lazy-loading.mdx` and `prefetching.mdx` to correctly reference the new streaming documentation, ensuring a cohesive and up-to-date knowledge base for users.

This commit significantly **enhances the security guidance for Server Actions** across the documentation, providing developers with clearer best practices. It updates several guides, including `mutating-data.mdx`, `data-security.mdx`, and `forms.mdx`, to emphasize and demonstrate robust **authentication and authorization checks** within Server Functions. This **documentation enhancement** also expands on topics like controlling return values, utilizing data access layers, and understanding how Server Functions interact with proxy rules, ultimately helping users build more secure applications.

This commit **fixes a critical issue** preventing `lerna` from running correctly within the **preview versioning script**. Previously, the `scripts/set-preview-version.js` script would encounter a `Detached git HEAD` error, causing `lerna` operations to fail during automated versioning. By adding a `git checkout` command to ensure a non-detached HEAD, this **maintenance fix** resolves the `ENOGIT` error. This change is crucial for the **stability of preview releases** and ensures that the automated versioning process can proceed without interruption.

This commit significantly **improves the documentation** for the `large-page-data` error within Next.js, specifically updating the `errors/large-page-data.mdx` page. The **documentation update** clarifies that this warning applies exclusively to the **Pages Router**, explains the `__NEXT_DATA__` mechanism and its performance implications on page weight and hydration, and provides actionable solutions like filtering or client-side fetching. It also documents the `experimental.largePageDataBytes` configuration option with a `next.config.js` example, offering developers comprehensive guidance to understand and resolve this issue. This **maintenance** effort enhances user understanding and troubleshooting for a common Next.js performance warning.

This commit **enhances the Next.js App Router documentation** to provide a clear solution for the "Uncached data or connection() was accessed outside of <Suspense>" error. It introduces a new section, "Opting Into Fully Dynamic Rendering" (or "Opting out of the static shell"), in `docs/01-app/01-getting-started/08-caching.mdx`, demonstrating how to wrap the root `<html>` in `<Suspense>` within `app/layout.tsx`. This **documentation improvement** offers a general pattern for users to achieve **fully dynamic rendering** without granular Suspense boundaries, addressing a common user query. Additionally, the `generateViewport` documentation is updated to better illustrate this root Suspense pattern.

This commit provides a **documentation update** for the **`create-next-app` CLI**, specifically affecting the `installation.mdx` and `create-next-app.mdx` files. It accurately reflects the CLI's behavior regarding the inclusion of `AGENTS.md` and `CLAUDE.md` files and updates the displayed default configuration prompts. The changes include adding the new `--agents-md` flag to the CLI options table and correcting descriptions for the `--yes` flag. This **maintenance** work ensures users have up-to-date information when using `create-next-app` to scaffold new Next.js projects.

This commit is a **documentation update** that significantly enhances the **Backend For Frontend (BFF) guide** by adding a new section on **content negotiation**. It explains how to implement content negotiation using **Next.js rewrites** and **Route Handlers** to serve different content types, such as Markdown, based on the `Accept` header. The new content also clarifies the importance of the `Vary: Accept` header for proper caching behavior. This **documentation enhancement** provides developers with practical guidance for building more flexible and robust content delivery systems.

This commit **fixes critical issues** with **`.next` directory handling** in the **`with-docker` and `with-docker-bun` Next.js examples**. It **removes a problematic BuildKit cache mount** on `.next/cache` from `examples/with-docker/Dockerfile` that trapped the fetch cache, making it unreachable by the runner stage. To ensure a writable prerender cache, it **restores `mkdir .next && chown` commands** in the runner stage of both `examples/with-docker/Dockerfile` and `examples/with-docker/Dockerfile.bun`. This **maintenance** work ensures these Docker examples build and run correctly, with updated documentation and an opt-in for persisting the build-time fetch cache.

This commit **introduces a new documentation guide** titled 'Preserving UI state across navigations', which details how to manage UI state using `Cache Components` and `React's Activity component`. It **refactors the existing documentation** by updating a link in `06-cache-components.mdx` to direct users to this more focused resource. This **documentation feature and refactoring** improves the clarity and accessibility of information within the **application guides**, providing a dedicated and comprehensive explanation of UI preservation patterns.

This commit **updates the documentation** for **`Activity` and `Cache Components`** within the application guides. It introduces a new **`useActionState` reset pattern** and incorporates guidance on global styles, providing developers with more comprehensive examples. Furthermore, the update **reframes existing recommendations** for managing UI state as choices, offering greater flexibility in decision-making. This **documentation enhancement** aims to improve clarity and provide more practical, pattern-based advice for developers utilizing these core components.

This commit provides crucial **documentation updates** to clarify the usage and availability of the `next upgrade` command. It explicitly states that this command is only available for **Next.js versions 16.1.x and above** within the **upgrading guide** (`docs/01-app/01-getting-started/18-upgrading.mdx`). Additionally, the **CLI reference documentation** (`docs/01-app/03-api-reference/06-cli/next.mdx`) for `next` is updated to note that `next upgrade` was introduced in v16.1.0. This **clarification** helps users understand the minimum version requirements, preventing potential confusion or issues when attempting to use the command on older Next.js installations.

This commit **updates the documentation** for **version staleness errors**, specifically within the `errors/version-staleness.mdx` file. The changes involve rephrasing the existing content to clarify the staleness notice, adding comprehensive upgrade instructions, and introducing new sections that detail different staleness levels and how to contribute. This **documentation improvement** aims to provide clearer guidance and better support for users encountering version staleness issues, enhancing their ability to understand and resolve these errors.

This commit significantly **enhances the documentation** for the **React Activity component** and its integration with **Cache Components** within Next.js applications. It introduces a **new comprehensive guide** on effectively using the `Activity` component, alongside a dedicated guide explaining how to handle complex UI patterns such as dropdowns and dialogs when combining `Activity` with `Cache Components`. This **documentation improvement** provides developers with clearer instructions and best practices, ensuring a smoother experience when building interactive features.

This commit **updates the documentation** for the `inlineCss` configuration option within `next.config.js`, specifically in the **API reference section**. The **documentation improvement** provides clearer and more detailed explanations of its trade-offs, guiding users on when to enable or skip `inlineCss` and when external CSS might be a more suitable choice. This enhancement helps developers make informed decisions regarding **CSS bundling strategies and application performance**.

This commit **improves the documentation** for the `next/image` component by enhancing the `next-image-unconfigured-localpatterns` error page. It now provides a more detailed explanation of how `pathname` and `search` parameters are matched within `localPatterns` configurations, along with common pitfalls. The update also includes more specific configuration examples, aiming to reduce user confusion and improve the developer experience when setting up image optimization for local assets. This **documentation enhancement** directly addresses user feedback regarding `next/image` configuration clarity, making it easier for developers to correctly configure image patterns.

This commit **updates the documentation** for the `adapterPath` configuration option within the `next.config.js` API reference. It refines the content by updating the title, adding an experimental version tag, and removing an outdated experimental warning. Additionally, this **documentation maintenance** task improves the readability of the `docs/01-app/03-api-reference/05-config/01-next-config-js/adapterPath.mdx` file by fixing spacing and list formatting. This ensures developers referencing the `adapterPath` configuration receive accurate and well-presented information.

This commit significantly enhances the **documentation** for Next.js **self-hosting**, particularly concerning **Server Actions** security and **deployment stability**. It clarifies the requirements for the `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` environment variable across various guides and error messages, and introduces a new **`deploymentId` configuration option** with dedicated pages. This **documentation update** provides crucial guidance for developers on preventing **version skew** and managing **shared caches** in multi-server environments, ensuring more robust and secure deployments.