This PR adds an error doc for the Middleware deprecation warning that it
can refer to.
- Explain why this error occurred
- Provide migration guide
- Explain the rationale for the renaming to Proxy
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
### What?
Updated Zod syntax to v4 conventions in documentation examples.
### Why?
Zod 4 deprecates `message` parameter in favor of `error`, and string
format methods like `.email()` in favor of top-level functions like
`z.email()`.
### How?
- Replaced `{ message: '...' }` with `{ error: '...' }`
- Changed `z.string().email()` to `z.email()`
---------
Co-authored-by: Maxim Andriushin <maksim.andriushin@gmail.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
As part of stabilizing `cacheComponents`, `cacheLife` profiles should
also be accessible from a top-level config. This updates the
configuration, adds the warning, and updates relevant docs.
This moves `experimental.cacheComponents` to a top level config. As part
of this, I disabled some tests in `build-output-prerender` that assert
on `cacheComponents` appearing in the experimental list. In a separate
PR, I'm going to show that Cache Components is enabled next to the
bundler info.
This also updates some docs pages to remove "experimental" language.
Follow up on https://github.com/vercel/next.js/pull/84710,
`instrumentation` docs had `onRequestError` function's param
`context.routeType` has value of `'middleware'`. As it's a user-facing
value, update it to `'proxy'`.
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>
Joseph
