Backport/docs fixes 16.2 - July round - #96031
Merged
Merged
Conversation
Before this guide existed, often we linked, incorrectly, to mutating-data. Also adding more related links pointing to this guide. (cherry picked from commit acd7610)
…es (#95148) ## Summary The `rewrites`, `headers`, and `redirects` config function examples in the docs are declared `async` but never `await` anything inside, which trips up linters (e.g. ESLint's `require-await` rule) for anyone who copies the example into `next.config.js`. These config options accept either a sync function or an async function (see the type in `packages/next/src/server/config-shared.ts`), so removing the unused `async` keyword does not change behavior. - Removed the unnecessary `async` keyword from every example in `rewrites.mdx`, `headers.mdx`, and `redirects.mdx` - Updated the accompanying prose ("is an async function" → "is a function") in each file Fixes #77598 ## Verification - `grep -rn "async rewrites() {\|async headers() {\|async redirects() {"` across the three files — no matches - `npx prettier --check` on the three changed files — passes - Not run: `pnpm lint` (`node_modules` not installed in this environment) <!-- NEXT_JS_LLM_PR --> --------- Co-authored-by: Joseph <sephxd1234@gmail.com> (cherry picked from commit 44684ab)
#95235) Fixes #62875 Removes the incorrect comment that `force-cache` is the default and can be omitted. In Next.js 15, fetch requests are no longer cached by default, so this statement was misleading for developers migrating to the App Router. <!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation - Run `pnpm prettier-fix` to fix formatting issues before opening the PR. - Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Signed commits - This repository requires verified commit signatures on protected branches. - If this pull request is blocked for unsigned commits, re-sign the commits and force-push the branch. - A `Signed-off-by` line in the commit message is not enough. ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> (cherry picked from commit b1eba13)
Link pointing back to its own section. (cherry picked from commit cecb6f3)
### What? Remove outdated experimental status notices for `@next/routing` from the adapters documentation and package README. ### Why? `@next/routing` is no longer experimental, and the existing notices incorrectly tie its stabilization to the adapters API. ### How? Delete the obsolete notices while leaving the routing API documentation unchanged. ### Verification - `pnpm prettier --with-node-modules --ignore-path .prettierignore --write docs/01-app/03-api-reference/07-adapters/05-routing-with-next-routing.mdx packages/next-routing/README.md` - Repository lint-staged checks passed during commit - Not run: runtime tests (documentation-only change) <!-- NEXT_JS_LLM_PR --> (cherry picked from commit 22fa026)
## Summary <img width="1304" height="1546" alt="CleanShot 2026-07-19 at 01 07 57@2x" src="https://github.com/user-attachments/assets/b9a6a7c9-dc95-42d5-9cce-f29e6d869d92" /> Adds a "Set up your editor" section to the App Router installation guide. The App Router names files by convention (`page.tsx`, `layout.tsx`, `route.ts`), so an editor quickly fills with same-named tabs. This section shows how to tell them apart with VS Code / Cursor custom editor labels, labeled two folders deep so dynamic routes like `blog/[id]/page.tsx` do not all collapse to the same `[id]` label. It includes: - A copy-paste `.vscode/settings.json` config (`workbench.editor.customLabels.patterns`) for setting it up by hand. - A copyable prompt that points a coding agent back at this section to apply the config, including adapting it to other editors. - A good-to-know that JetBrains IDEs (WebStorm, IntelliJ) do this automatically. ## Verification - Previewed locally against the docs site: the section renders (HTTP 200), with the config block, the prompt card, and the good-to-know all rendering correctly. <!-- NEXT_JS_LLM_PR --> (cherry picked from commit 03701be)
### What? - Adds one clarifying sentence (plus a link) to the "Organize routes without affecting the URL path" section in docs/01-app/01-getting-started/02-project-structure.mdx. No behavior change, docs text only. --- ### Why? - The existing sentence says you can add a layout.js inside a route group folder to give it a different layout, but it doesn't say whether that layout.js nests inside the top-level app/layout.js or replaces it. Read in order, a reader hits this line before the page ever mentions removing the top-level layout, so it's genuinely ambiguous at that point in the page. The nesting behavior is only clarified later, in the "Creating multiple root layouts" section — and even then, it's explained for a different, more specific case (removing the top-level layout entirely to give each route group its own root layout). --- ### How? - Added one sentence stating that this layout.js nests inside the top-level app/layout.js like any other layout by default, and linked to "Creating multiple root layouts" for readers who want the root-layout behavior instead. --------- Co-authored-by: Joseph <sephxd1234@gmail.com> (cherry picked from commit 13dad0d)
**What**: Included the examples of static export tools seen in the [Getting Started guide on deploying with static exports](https://nextjs.org/docs/app/getting-started/deploying#static-export). Added a reference to the official Next.js GitHub Pages template. **Why**: Per discussion #95756, the GitHub Pages template provided by Next.js can be somewhat easily missed. Its addition to a second location can alleviate this issue. **How**: A part of the language used in the Static Exports section of the Getting Started article was already present in the Static Exports guide. Therefore, the least obtrusive way to add the reference to the GitHub Pages template was to include it in said language. <!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors We encourage you to use AI to assist you in researching, creating, and reviewing changes. However, you must review and deeply understand the contributions you are making. For this reason, **pull request descriptions from external contributors must be written by a human**. ### Improving Documentation - Run `pnpm prettier-fix` to fix formatting issues before opening the PR. - Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Signed commits - This repository requires verified commit signatures on protected branches. - If this pull request is blocked for unsigned commits, re-sign the commits and force-push the branch. - A `Signed-off-by` line in the commit message is not enough. ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> --------- Co-authored-by: Joseph <sephxd1234@gmail.com> (cherry picked from commit 3b7946d)
The function signature was wrong:
```tsx
function Page({ params } }){
```
Which also prevented prettier from running in the code block. This PR
fixes the signature and formats the code block.
(cherry picked from commit f54dbb9)
Replace the incorrect `<Artist>` reference with `getArtist()` to clarify the dependency in the sequential fetching example. ### What? Replace the incorrect <Artist> reference with getArtist(). ### Why? To accurately describe the sequential data dependency. ### How? Update the wording in the data-fetching documentation. (cherry picked from commit e23fe06)
Contributor
Stats skippedCommit: 3ffaea4 |
Contributor
Tests PassedCommit: 3ffaea4 |
[Live page](https://nextjs.org/docs/app/guides/debugging) links to: https://nodejs.org/en/docs/guides/debugging-getting-started Which is 404 now Seems like this is where it should point now: https://nodejs.org/learn/getting-started/debugging (cherry picked from commit 01a2363)
## What Updates one broken URL in the debugging guide that returns 404. ```diff -For help, see: https://nodejs.org/en/docs/inspector +For help, see: https://nodejs.org/api/inspector.html ``` The old path (`/en/docs/inspector`) no longer exists after Node.js restructured their documentation site. The replacement points to the current Node.js Inspector API docs which returns 200. ## Why This URL appears inside a terminal output code block showing what the Node.js debugger prints when launched with `--inspect`. A reader who follows the link to learn more about the inspector gets a 404. A related fix for the separate Debugging Guide link (`/en/docs/guides/debugging-getting-started`) is tracked in #93958. This PR addresses the second broken Node.js URL in the same file that #93958 did not cover. ## Checklist - [x] Docs-only change. No behavior impact. - [x] Replacement URL verified to return HTTP 200. <!-- NEXT_JS_LLM_PR --> (cherry picked from commit c5a826f)
…orts (#95056) ### What? - New **Auth and streaming** subsection under `### Layouts and auth checks` explaining how a top-level `await` in a layout delays the first streamed chunk, and how to push the access into a nested `<Suspense>` boundary. Links to [Push dynamic access down](/docs/app/guides/streaming#push-dynamic-access-down) and to [Sharing data with context and `React.cache`](/docs/app/getting-started/fetching-data#sharing-data-with-context-and-reactcache). - Tightens the surrounding DAL paragraph (anchor link, "prevents developers from forgetting"). - Fixes a few small bugs in surrounding code samples: default `cookies` imports (twice), `app/layout.ts` for a file with JSX, and two malformed code-fence directives in the Profile examples. <!-- NEXT_JS_LLM_PR --> (cherry picked from commit db56533)
aurorascharff
approved these changes
Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
11 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary