This PR removes middleware docs and adds a "Migration to Proxy" section
to the Proxy docs, which explains the rationale for the renaming to
Proxy and provides a migration guide.
Did not remove `middleware-upgrade-docs` as it's an upgrade doc from the
legacy middleware.
Below are untouched as they need codebase changes:
- `instrumentation` docs - `onRequestError` has `context.routeType` as
`'middleware'`
- `adapterPath` docs - has `MiddlewareMatcher` type example
- `ProxyConfig` - has a user-facing `MiddlewareMatcher` type
---------
Co-authored-by: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
> [!NOTE]
> Best reviewed by each commit for better diff view.
This PR clones the Middleware docs for Proxy and removes the Middleware docs.
Did not clone the list of docs:
- `errors/middleware-upgrade.mdx` - It's a middleware upgrade guide from v12.2
- `errors/beta-middleware.mdx` - It's an error when using middleware before v12.2
- `errors/returning-response-body.mdx` - Legacy behavior from versions < v12.2
This PR splits the route handlers and middleware to allow for separate
onboarding docs, making it easier to migrate the docs from Middleware to
Proxy.
These PR stacks are to publish a full replacement of the docs for the
Middleware to Proxy. Steps are as follows:
- Split "Get Started: Route Handlers and middleware" to Route Handlers /
Proxy
- Clone the Middleware docs for Proxy
- Add "Migration to Proxy" section to Middleware docs
- Explain the rationale for the renaming to Proxy
- Provide migration guide
- Add an error doc that the deprecation warning can refer to. The error
doc will:
- Explain why this error occurred
- Provide migration guide
- Explain the rationale for the renaming to Proxy
## What
Updated `prefetching.mdx` in the App Router documentation providing more
clarity on the usage of `router.prefetch()`.
## Why
We found the current section on `Manual Prefetching` to be lacking in
detail and a bit misleading as well.
The issue with the current version of the documentation is that the code
snippet provided:
```tsx
const router = useRouter();
router.prefetch();
```
Makes it seem like `router.prefetch()` can be called at the same level
as `useRouter()`, i.e. in the component body, even though that causes
the page to crash for many possible reasons, such as `window is not
defined`, or `Router action dispatched before initialization.`.
I am not sure if this is helpful/correct or not, just thought this may
help someone. If not feel free to close this PR. Thanks in advance for
your time.
## Reproduction
Here is a codesandbox reproducing the issue that occurs if you follow
the code snippet trivially:
https://codesandbox.io/p/devbox/s5pmsj
<!-- 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. (Done)
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide (Done)
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
As part of stabilizing cacheComponents, we are also stabilizing
supporting flags. This flag has been enabled with cacheComponents for
some time and so we are moving it out of experimental.
It will continue to be enabled by default if you are using
cacheComponents. Otherwise, it can be opted into independently via next
config.
Closes https://linear.app/vercel/issue/NDX-1048
Closes https://github.com/vercel/next.js/pull/80317
---------
Co-authored-by: Sebastian "Sebbie" Silbermann <sebastian.silbermann@vercel.com>
Reworking and re-organizing the next/dynamic section - headings were not
consistent for Pages Router. The Pages router section also talked about
client and server components.
This optimization is enabled by default and we already link to the docs so referencing the configuration option is more misleading than helpful.
Fixes https://github.com/vercel/feedback/issues/111264
### What?
Adds build-time validation to require explicit `default.js` files for
all parallel route slots (except the implicit "children" slot). This
validation is implemented in both Webpack and Turbopack bundlers.
### Why?
Parallel routes without `default.js` files currently cause silent 404
errors when users navigate to those routes. This creates confusion and
hard-to-debug issues because the routes appear to be configured
correctly but fail at runtime without any indication of what went wrong.
By making this validation explicit at build time, developers get
immediate feedback about missing required files with clear error
messages and documentation links, catching configuration mistakes before
deployment.
### How?
**Rust/Turbopack** (`crates/next-core/src/app_structure.rs`): Added
`MissingDefaultParallelRouteIssue` that emits a build error when a
parallel route slot is missing its `default.js` file. The validation is
skipped for the "children" slot since it's implicit and doesn't require
a default file.
**Webpack**
(`packages/next/src/build/webpack/loaders/next-app-loader/index.ts`):
Added validation that throws `MissingDefaultParallelRouteError` when
`default.js` cannot be resolved. The "children" slot falls back to the
existing `PARALLEL_ROUTE_DEFAULT_PATH` behavior for backward
compatibility.
**Error Class**
(`packages/next/src/shared/lib/errors/missing-default-parallel-route-error.ts`):
New error type with helpful messaging that includes the slot path,
explanation of the requirement, and a link to documentation.
**Migration Path**: Users who want the previous 404 behavior can
explicitly create a `default.js` that calls `notFound()`, or return
`null` for empty slots:
```tsx
import { notFound } from 'next/navigation'
export default function Default() {
notFound()
}
```
Users can also run the following Deno script to generate the default
files for them:
https://gist.github.com/wyattjoh/ba7263ecb637ef399d3e3e4db63ffbd6
**Breaking Change**: This is a breaking change timed for Next.js 16
beta. Builds will now fail if parallel route slots are missing required
`default.js` files.
This PR adds a two new options and sets a strict default value for each.
- `images.dangerouslyAllowLocalIP`
- `images.maximumRedirects`
### dangerouslyAllowLocalIP
In rare cases when self-hosting Next.js on a private network, you may
want to allow optimizing images from local IP addresses on the same
network.
However, this is not recommended for most users so the default is
`false`.
> [!NOTE]
> BREAKING CHANGE: This change is breaking for those who self-hosting
Next.js on a private network and want to allow optimizing images from
local IP addresses on the same network. In those cases, you can still
enable the config.
### maximumRedirects
Since are also testing redirects for local IPs, we can also reduce the
maximum number of redirects to 3 by default.
Unlike normal websites which might redirect for features like auth, its
unusual to have more than 3 redirects for an image.
In some rare cases, developers may need to increase this value or set to
`0` to disable redirects.
> [!NOTE]
> BREAKING CHANGE: This change is breaking for those who need image
optimization to follow more than 3 redirects.
This PR modifies Image behavior to require `images.localPatterns.search`
value when used with search queries in the `src` property:
```jsx
// Error
<Image src="/api/user?id=1" width="50" height="50" />
```
```ts
// next.config.ts
export default {
images: {
localPatterns: [
{
pathname: '/api/user',
// Either set explicit query string or leave undefined to match all
search: '?v=2',
},
],
},
}
```
It is to prevent malicious actors like Denial of Wallet (DoW) attacks
and strictly match the search queries for image optimization.
The deprecation warning was added at
https://github.com/vercel/next.js/pull/82627
---------
Co-authored-by: Steven <steven@ceriously.com>
This provides a way to refresh the client cache from within a server
action. This is useful when you need to refresh the client UI / read
your writes without needing to rely on `updateTag`.
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
<!-- 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?
### Why?
### How?
Closes NEXT-
Fixes #
-->
### What?
Make a note about the `$ACTION_` properties in `formData`
### Why?
Starting with next@14.1.3, `$ACTION_` properties have appeared in the
`formData`, which cause validation errors when used with a strict
validation with a library such as Zod or Yup:
```tsx
// Form Client Component
export default function Form() {
const [state, formAction] = useFormState(action, {
type: 'initial',
});
return (
<form action={action}>
{/* ... */}
</form>
);
}
// Server Action
export async function action(
prevState: ServerActionReturnValue,
formData: FormData,
): Promise<ServerActionReturnValue> {
const validationResult = await schema.validate(
Object.fromEntries(formData.entries()),
);
```
The errors from Yup:
Errors:
- this field has unspecified keys: $ACTION_REF_1, $ACTION_1:0,
$ACTION_1:1, $ACTION_KEY
The data in the formData.entries()
```js
{
'$ACTION_REF_1': '',
'$ACTION_1:0': '{"id":"59f475b...","bound":"$@1"}',
'$ACTION_1:1': '[{"type":"initial"}]',
'$ACTION_KEY': 'k187677481',
// Real form data starts here:
year: '2024',
```
### How?
1. Document additional properties with keys starting with the prefix
`$ACTION_`
2. Remove the obsolete mention of `.entries()`, since that is not being
used in the code example anymore (previously, it was `const rawFormData
= Object.fromEntries(formData.entries())`)
### History
- The `$ACTION_` property change was added in
https://github.com/vercel/next.js/pull/63048
- The `docs/01-app/02-guides/forms.mdx` file was added in PR
https://github.com/vercel/next.js/pull/79288 , without the `$ACTION_`
property change
cc @delbaoliveira
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
### What?
Statsig is a popular AB Testing/ Feature Flagging solution to use in concert with Next.js. Today, their newest Server SDK doesn't play nicely with Next as its build around a Rust library, which doesn't play nice with webpack and causes build issues.
### Why?
This'll remove a step for Statsig/Next developers having to troubleshoot and add @statsig/statsig-node-core to serverExternalPackages themselves.
### How?
Added to the list published here: https://nextjs.org/docs/app/api-reference/config/next-config-js/serverExternalPackages
We took a look at unique Next.js projects that have one or more requests
for a specific image size and here are the findings as seen from the
Image Optimization API:
- `w=16` 4.2%
- `w=32` 17.1%
- `w=48` 21.4%
- `w=64` 22.6%
- `w=96` 25.8%
- `w=128` 29.5%
- `w=256` 46.5%
- `w=384` 35.1%
- `w=640` 57.2%
Only 4.2% of Next.js projects ever made a request to a 16px width image.
This is low enough to remove from the default configuration so that all
other projects can benefit from reduced html
[srcset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset)
and fewer variations exposed from the backend API.
You might think that this means few developers are using `<Image
width={16} />` but it probably means that most displays nowadays use
devicePixelRatio 2 meaning that specifying a 16px image width will
actually fetch the 32px width to ensure it won't looking blurry on your
retina display.
BREAKING CHANGE: this is technically a breaking change but it won't
cause apps to stop working, its just 4% of them may have some requests
serve a 32px image instead of 16px. Those apps can of course opt in by
changing their `images.imageSizes` config back to allowing 16.
### What?
This PR removes the automatic ESLint linting that previously ran during `next build`. The documentation has been updated to reflect this change.
### Why?
As part of Next.js 16, we're removing the automatic build-time linting that was previously included in the build process. This gives developers more control over when linting runs by explicitly invoking their linter via npm scripts.
### How?
- Updated documentation to clarify that automatic build-time linting has been removed in Next.js 16
- Removed the `runLint` parameter and related linting code from the build process
- Removed the `verifyAndLint.ts` file which is no longer needed
- Simplified type checking code by removing lint-related functionality
- Removed ESLint telemetry during builds
### What?
- Adding a small note to clarify the meaning of the phrase "project
root" in the documentation for next.config output, specifically in
regards to a monorepo setup
### Why?
- While doing some debugging related to a container that I cannot build
locally for compliance reasons, I had to take shots in the dark to
figure this behavior out 😄 hoping it can help the next soul who finds
themselves in a similar predicament
### How?
- Explain that in monorepos, "project root" does not mean the root of
the monorepo, but instead the root of the nextjs app
First time contributing, so I appreciate any reviews/feedback I can get
here, even for such a small PR. Thanks!
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
This doc is mainly to provide the users with information on how to opt
out of this feature. We could later remove these docs and the option
when the need to opt out is low.
---------
Co-authored-by: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
This was docs deprecated in Next.js 14 so we should begin warning in
Next.js 16 when `images.domains` config is used.
This will guide users to providing a strict `images.remotePatterns`
config ensuring only expected images can be optimized.
Add missing space before "Importing Client Components" in Lazy Loading
/app docs.
This fixes the missing link in "On this page" sidebar:
<img width="1092" height="446" alt="image"
src="https://github.com/user-attachments/assets/0981467d-ad61-494d-80b2-c0a0e323dd0b"
/>
In the current state, the first link is "Skipping SSR" (second link)
instead of "Importing Client Components"
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
PR title - docs: polish Project Structure page (grammar, consistency,
clarity)
PR description -
1) Fixes an Oxford comma in the routing files description for
consistency.
2) Normalizes heading capitalization to sentence case.
3) Corrects “Files conventions” → “File conventions”.
4) Aligns not-found.js description with earlier table (it’s not an error
boundary). Clarifies intercepting routes microcopy.
<!-- 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?
### Why?
### How?
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Jiwon Choi
