Skip to content

[backport] docs: late September improvements and fixes #84334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 9 commits into
base: next-15-5
Choose a base branch
from
Draft

[backport] docs: late September improvements and fixes #84334

wants to merge 9 commits into from

Conversation

icyJoseph
Copy link
Contributor

Additional group of docs improvements.

icyJoseph and others added 7 commits September 29, 2025 11:04
@icyJoseph
Docs/getting started improv (#82741)
c67febd 
Part of:
https://linear.app/vercel/issue/DOC-4809/layout-pages-and-linking-and-navigating-improvements

Iterating a bunch of improvements to getting-started
@icyJoseph
docs: onRequestError request header type (#83988)
8c41a6d 
Aligning with the actual type
https://github.com/vercel/next.js/blob/canary/packages/next/src/server/instrumentation/types.ts#L18
@martinfrancois @icyJoseph
Fix TypeScript type error in example code (#84041)
e36b2de 
Without the `| null`, the following error appears during compilation:
```
TS2322: Type RefObject<HTMLDivElement | null> is not assignable to type RefObject<HTMLDivElement>
Type HTMLDivElement | null is not assignable to type HTMLDivElement
Type null is not assignable to type HTMLDivElement
```

Co-authored-by: Joseph <[email protected]>
@liketiger @icyJoseph
docs: improve dynamic routes example in project structure page (#84086)
5b69afe 
## Documentation Update

This PR improves the dynamic routes example in the
`project-structure.mdx` page.

### Changes
- Updated catch-all segments example:
  - Before: `/shop/clothing/shoes`
  - After:  `/shop/clothing`
- Adjusted follow-up examples for consistency:
  - `/shop/a`, `/shop/a/b` → `/shop/clothing`, `/shop/clothing/shirts`

### Why
- Provides a clearer and more intuitive demonstration of how catch-all
segments work.
- Keeps the example consistent with other dynamic routes documentation.

Co-authored-by: Joseph <[email protected]>
@icyJoseph
docs: We have dropped the CORS example linked (#84065)
0c846de 
We have dropped the example linked in this page. I'll re-evaluate later
if the section is still enough for a dev to understand how to set CORS
related headers.
@Milancen123 @icyJoseph
docs: add pageExtensions note to Middleware and clarify default filen…
961a0f5 
…ame (#84045)

- Added a Note to the Middleware docs explaining that when
`pageExtensions` are customized (e.g. `.page.ts`), the Middleware file
should be named `middleware.page.ts` or `middleware.page.js`.
- Updated wording so `middleware.ts/js` is described as the default
filename, not a strict requirement.

<!-- 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


## 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?

-Added a callout note to middleware.mdx stating that if pageExtensions
is customized (e.g., .page.ts), the Middleware file should also match
(middleware.page.ts/js).
-Updated the language from “must” → “default is” for filename clarity.


### Why?

-Developers customizing pageExtensions were misled by the existing docs,
which implied middleware.ts/js was always required.
-This PR prevents confusion when Middleware isn’t recognized after a
pageExtensions change.


### How?
Edited docs/app/api-reference/file-conventions/middleware.mdx.
Inserted a > **Note** block right after the paragraph explaining where
to create the middleware file.


Closes NEXT-
Fixes #84008

-->

---------

Co-authored-by: Joseph <[email protected]>
@icyJoseph
docs: nav_title for long unbroken words (#84233)
895f0f5 
Let's use a different title for these, otherwise we have a very long
composite word.
@ijjk ijjk added created-by: Next.js DevEx team PRs by the DX team. Documentation Related to Next.js' official documentation. labels Sep 29, 2025
@ijjk
Copy link
Member

ijjk commented Sep 29, 2025 •
edited
Loading

Failing test suites

Commit: 0d47599 | About building and testing Next.js

pnpm test-start-turbo test/e2e/app-dir/back-forward-cache/back-forward-cache.test.ts (turbopack)

  • back/forward cache > React state is preserved when navigating with back/forward buttons (DD)
  • back/forward cache > React state is preserved when navigating back/forward with links (DD)
  • back/forward cache > React state is preserved when navigating back to a page with different search params than before (DD)
  • back/forward cache > bfcache only preserves up to N entries (DD)
  • back/forward cache > navigate back and forth repeatedly between the same pages without evicting (DD)
Expand output

● back/forward cache › React state is preserved when navigating with back/forward buttons

next build failed with code/signal 1

  107 |             if (code || signal)
  108 |               reject(
> 109 |                 new Error(
      |                 ^
  110 |                   `next build failed with code/signal ${code || signal}`
  111 |                 )
  112 |               )

  at ChildProcess.<anonymous> (lib/next-modes/next-start.ts:109:17)

● back/forward cache › React state is preserved when navigating back/forward with links

next build failed with code/signal 1

  107 |             if (code || signal)
  108 |               reject(
> 109 |                 new Error(
      |                 ^
  110 |                   `next build failed with code/signal ${code || signal}`
  111 |                 )
  112 |               )

  at ChildProcess.<anonymous> (lib/next-modes/next-start.ts:109:17)

● back/forward cache › React state is preserved when navigating back to a page with different search params than before

next build failed with code/signal 1

  107 |             if (code || signal)
  108 |               reject(
> 109 |                 new Error(
      |                 ^
  110 |                   `next build failed with code/signal ${code || signal}`
  111 |                 )
  112 |               )

  at ChildProcess.<anonymous> (lib/next-modes/next-start.ts:109:17)

● back/forward cache › bfcache only preserves up to N entries

next build failed with code/signal 1

  107 |             if (code || signal)
  108 |               reject(
> 109 |                 new Error(
      |                 ^
  110 |                   `next build failed with code/signal ${code || signal}`
  111 |                 )
  112 |               )

  at ChildProcess.<anonymous> (lib/next-modes/next-start.ts:109:17)

● back/forward cache › navigate back and forth repeatedly between the same pages without evicting

next build failed with code/signal 1

  107 |             if (code || signal)
  108 |               reject(
> 109 |                 new Error(
      |                 ^
  110 |                   `next build failed with code/signal ${code || signal}`
  111 |                 )
  112 |               )

  at ChildProcess.<anonymous> (lib/next-modes/next-start.ts:109:17)

pnpm test-dev test/development/acceptance-app/undefined-default-export.test.ts

  • Undefined default export > should error when page component export is not valid (DD)
Expand output

● Undefined default export › should error when page component export is not valid

expect(received).toMatchInlineSnapshot(snapshot)

Snapshot name: `Undefined default export should error when page component export is not valid 1`

- Snapshot  - 7
+ Received  + 1

- {
-   "description": "The default export is not a React Component in "/page"",
-   "environmentLabel": null,
-   "label": "Runtime Error",
-   "source": null,
-   "stack": [],
- }
+ "Expected Redbox but found no visible one."

   98 |     }, 10_000)
   99 |
> 100 |     await expect(browser).toDisplayRedbox(`
      |                           ^
  101 |      {
  102 |        "description": "The default export is not a React Component in "/page"",
  103 |        "environmentLabel": null,

  at Object.toDisplayRedbox (development/acceptance-app/undefined-default-export.test.ts:100:27)

__NEXT_EXPERIMENTAL_PPR=true pnpm test-dev test/e2e/app-dir/navigation/navigation.test.ts (PPR)

  • app dir - navigation > middleware redirect > should change browser location when router.refresh() gets a redirect response (DD)
Expand output

● app dir - navigation › middleware redirect › should change browser location when router.refresh() gets a redirect response

expect(received).toBe(expected) // Object.is equality

Expected: "http://localhost:37349/redirect-on-refresh/dashboard"
Received: "http://localhost:37349/redirect-on-refresh/auth"

  984 |       const browser = await next.browser('/redirect-on-refresh/auth')
  985 |       await retry(async () =>
> 986 |         expect(await browser.url()).toBe(
      |                                     ^
  987 |           next.url + '/redirect-on-refresh/dashboard'
  988 |         )
  989 |       )

  at toBe (e2e/app-dir/navigation/navigation.test.ts:986:37)
  at retry (lib/next-test-utils.ts:813:14)
  at Object.<anonymous> (e2e/app-dir/navigation/navigation.test.ts:985:7)

pnpm test-dev test/e2e/app-dir/actions/app-action-node-middleware.test.ts

  • app-dir action handling > fetch actions > should handle redirects to routes that provide an invalid RSC response (DD)
Expand output

● app-dir action handling › fetch actions › should handle redirects to routes that provide an invalid RSC response

expect(received).toContain(expected) // indexOf

Expected substring: "Hello from a pages route"
Received string:    "0.6744078498994239
Client
Server
Client and Server
0
+1+1 (Slow)-1*2
redirect to a pages route
submit
test"

  1311 |
  1312 |       await retry(async () => {
> 1313 |         expect(await browser.elementByCss('body').text()).toContain(
       |                                                           ^
  1314 |           'Hello from a pages route'
  1315 |         )
  1316 |         expect(await browser.url()).toBe(`${next.url}/pages-dir`)

  at toContain (e2e/app-dir/actions/app-action.test.ts:1313:59)
  at retry (lib/next-test-utils.ts:813:14)
  at Object.<anonymous> (e2e/app-dir/actions/app-action.test.ts:1312:7)

icyJoseph and others added 2 commits September 29, 2025 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
created-by: Next.js DevEx team PRs by the DX team. Documentation Related to Next.js' official documentation.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@icyJoseph @ijjk @martinfrancois @liketiger @Milancen123 @geraldochristiano