### What?
`use` is not a hook. It's highlighted in the doc
> Unlike React Hooks, use can be called within loops and conditional
statements like if. Like React Hooks, the function that calls use must
be a Component or Hook.
### Why?
It confuses consumers of Next.js and adds field provide misleading
proofs
### How?
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Joseph <[email protected]>
Co-authored-by: Joseph <[email protected]>
This PR implements the initial version of dev-time validation for
`export const instant = ...`
```tsx
export const instant = { prefetch: 'static' }
```
```tsx
export const instant = { prefetch: 'runtime', ... }
```
```tsx
export const instant = false
```
(the config is currently expected to be named `unstable_instant`, but
i'll be shortening it to `instant` below.)
When a segment specifies an instant config with `prefetch: 'static'` or
`prefetch: 'runtime'`, we'll validate that all (prefetched) navigations
into that segment will render instant UI, i.e. that the navigation won't
block. On the other hand, if a segment is allowed to block, it must be
marked with `export const instant = false`.
Note that our existing static shell validation is a special case of
this, but for now, we're keeping both. A future PR will reimplement
static shell validation as a special case of instant validation.
Like static shell validation, these validations currently run in dev
whenever we render the full page (i.e. no segments are omitted). This
means it'll happen on an initial load (or refresh) and HMR.
### Implementation notes
#### Validation approach
The goal is to simulate what the browser would display for a prefetched
client navigation. We do this by re-assembling the segments extracted
from the original stream for the page.
- The outer (shared) segments should already fully resolved (i.e. in the
Dynamic stage), to represent the fact that the browser loaded them
before
- The new segments are either in Static or Runtime stage, depending on
how each segment would have been prefetched.
Similar to static shell validation, we then perform a Fizz prerender on
the combined payload, abort it, and track the locations of `onError`
calls. The difference here is that unlike static shell validation, we
require a Suspense boundary *inside* the new subtree. This is detected
by adding a `InstantValidationBoundary` around the new subtree when we
construct the payload, and checking if there's a suspense below that in
the component stack.
Currently, for each `instant` config we find, we take each of its parent
layouts as a possible navigation parent (unless it's marked as
blocking). So if we have a page with parent layouts like this:
```
/layout.tsx
/foo/layout.tsx
/foo/bar/layout.tsx
/foo/bar/page.tsx <- `export const instant = { prefetch: 'static' }`
```
Then we'll check for navigations where each of `/layout.tsx`,
`/foo/layout.tsx` and `/foo/bar/layout.tsx` is a fully resolved shared
parent.
If a validation fails, we do a "discriminated error message" flow
analogous to static shell validation. Static segments are replaced with
Runtime segments to see if the error goes away, which lets us determine
if the hole is caused by runtime or dynamic data.
#### Building the combined payload
First, we need to separate the full stream into segments. The process is
similar to `collectSegmentData` -- we need to deserialize the payload
from the stream and then re-serialize each segment separately. The
complexity here comes from the fact that the full stream is separated
into stages, and we need each segment to be in staged form as well. This
lets us pick and choose which stage the segment is in to simulate what
we'd show for a static or runtime prefetch.
The other complex part is the "late release trick" (as implemented in
`createNodeStreamWithLateRelease`). This was already done for static
shell validation, but it's more complex here.
Debug info for dynamic holes is usually delayed until a further stage.
So, in the static stage we only see an unresolved promise (or lazy
reference), and then in the runtime stage we get the debugInfo telling
us that it was caused by `await cookies()`. To ensure that this debug
info is available for purposes on error reporting, we do a "late
release" -- before we abort, we advance the each segment to the dynamic
stage, which won't cause any new content to render, but will provide
Fizz with debug info and thus give us precise error locations in
`onError`. If you see `releaseSignal`, that's what it's for.
#### `instant` on layouts
We support specifying `instant` on layouts. The validation principle is
the same, but note that in the current mode (validating a single page in
dev) we can't enforce that *all* navigations into that layout satisfy
the constraint, we can only check if that's satisfied for the current
page.
#### Blocking segments
A segment can be marked as blocking with
```tsx
export const instant = false
```
This is meant to signal that this segment deliberately does not have
instant UI.
Currently, this is affects validation as follows:
If there's no `instant` config in parent segments, skip validating all
navigations where this layout would be new (because we know it'd block),
i.e. only validate navigations where it's a shared parent. Children of
this segment can still have `instant` configs of their own, and those
will be validated. This allows structures where a layout is blocking,
but once it's loaded, navigations within it should have instant UI.
If there is an `instant` config in a parent segment, the validation of
that parent is *not* skipped. The reasoning here is that if a layout
asserts that navigations into it should have static UI, then a child
with `instant = false` should not violate that. This essentially
requires that the child have a `loading.js` or that the layout has to
wrap the slot with Suspense.
Note that `instant = false` can also be used to opt segements out of
static shell validation without requiring a Suspense above body.
### Limitations and planned follow-ups
- `instant` configs in parallel routes (i.e. `@slot`) are not currently
validated.
- `expectUnableToVerify` is not implemented yet, i.e. there's no way to
say "this cannot be validated using SSR". The shared segments are not
expected to suspend. For now, `export const instant = { prefetch: ...,
unstable_disableValidation: true }` can be used to bypass a segment if
validating it causes problems.
- static shell validation is a special case of instant validation, but
is not currently implemented as such.
- we should be able to validate during client navigations, not just
full-page loads and HMR, but we currently can't because we don't have
all the segments when we do that, so we can't assemble a proper combined
payload.
This PR adds error handling for nested `"use cache"` where the inner
cache has a very short lifetime (zero `revalidate` or `expire` under 5
minutes) but the outer cache doesn't have an explicit `cacheLife()`
call.
Short-lived caches become "dynamic holes" that are excluded from
prerenders. When such a cache is nested inside another `"use cache"`
without an explicit `cacheLife`, the outer cache's lifetime would
silently become short too via
[propagation](https://nextjs.org/docs/app/api-reference/functions/cacheLife#nested-caching-behavior),
which can lead to unexpected behavior. To prevent this accidental
misconfiguration, Next.js now throws an error during prerendering,
requiring developers to explicitly declare their intent by adding
`cacheLife()` to the outer cache.
The implementation tracks whether `revalidate` and `expire` were
explicitly set via `hasExplicitRevalidate` and `hasExplicitExpire` flags
on the collected cache result. Errors are wrapped with
`wrapAsInvalidDynamicUsageError` to capture proper stack traces and
prevent userland try/catch from suppressing the build error.
Documentation has been updated with a new "Prerendering behavior"
section in the `cacheLife` API reference explaining how short-lived
caches become dynamic holes, and a "Nested short-lived caches"
subsection with examples showing how to fix the error.
closes NAR-761
Mostly mechanical rename.
Also changes the error page to `errors/invalid-instant-configuration`.
I'm not really worried about dangling links here because this is a new
API and we don't expect anyone to be using it yet.
Original [PR](https://github.com/vercel/next.js/pull/88012/) has a bug
that attempted to validate on environment variables. Edited function to
not run validations on environment variables, only on the user provided
deployment id.
<!-- 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: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: JJ Kasper <[email protected]>
Note: new PR description written by @timneutkens
## What?
Improves the detection of Google Tag Manager vs Google Analytics.
As indicated by the author of this PR it was confusing that when you
have Google Tag Manager set up it gives you an error message saying
you're adding Google Analytics even though it's Tag Manager.
I've updated the PR to have a separate message for Google Tag Manager
and expanded the error message docs too.
It also mentioned `next/script` in a bunch of places even though the
error doc recommends `@next/third-parties`. I've updated all cases to
refer to `@next/third-parties` instead.
<details>
<summary>Previous PR description</summary>
Google has multiple products with similar names: the "Google Tag" and
"Google Tag Manager". Google Tag Manager uses `gtm.js` whereas the
"Google Tag" uses `gtag`. Google Analytics previously used
`analytics.js` (<2017) and is now delivered via the "Google Tag".
Google Tag: `www.googletagmanager.com/gtag/js`
Google Tag Manager: `www.googletagmanager.com/gtm.js`
The `next-script-for-ga.ts` rule's matching list
(`SUPPORTED_HTML_CONTENT_URLS`) includes `gtm.js` which means when a
developer adds Google Tag Manager to their NextJS website, they'll
receive the warning and be encouraged to swap from `gtm.js` to `gtag`. A
developer asleep at the wheel (...me) may think...
> I'm using Google Analytics via Google Tag Manager, and NextJS is
suggesting I swap `gtm.js` for `gtag` because it will improve
performance. `gtag` sounds like it is part of "Google Tag Manager" so I
am going to follow the instructions so that my website is faster.
However, `gtag` is **not** compatible with `gtm.js` (they're different
products with similar names and similar purposes) and so making this
change will cause very confusing Google Tag Manager behaviour. I am
suggesting that `gtm.js` is removed completely from the rule, because
anyone using `gtm.js` should not be following these instructions. A
separate rule could be added specifically for Google Tag Manager, that
does not refer to `gtag`.
</details>
---------
Co-authored-by: Tim Neutkens <[email protected]>
I think maybe these others need a hint too, let's get started with,
`errors/missing-suspense-with-csr-bailout` and `errors/prerender-error`
- errors/blocking-route.mdx
- errors/deopted-into-client-rendering.mdx
- errors/dynamic-server-error.mdx
- errors/next-prerender-crypto.mdx
- errors/next-prerender-current-time.mdx
- errors/next-prerender-sync-headers.mdx
- errors/next-prerender-sync-params.mdx
- errors/sync-dynamic-apis.mdx
Prior to this change any "hole" in a prerender that would block the
shell was considered an error and you would be presented with a very
generic message explaining all the different ways you could have failed
this validation check.
With this change we use a new technique to validate the static shell
which can now tell the difference between waiting on uncached data or
runtime data. It also improves the heuristics around generateMetadata
and generateViewport errors.
Added new error pages for runtime sync IO and ensure we only validate
sync IO after runtime data if the page will be validating runtime
prefetches.
Restored the validation on HMR update so you can get feedback after
saving a new file.
---
We've also discovered that hanging inputs are not handled correctly.
Fixing this is non-trivial and will be done in a follow-up, so for now,
we're disabling the failing tests.
---------
Co-authored-by: Josh Story <[email protected]>
Co-authored-by: Hendrik Liebau <[email protected]>
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 <[email protected]>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
### What?
This PR adds build-time validation that requires `generateStaticParams`
to return at least one result when Cache Components (experimental
`cacheComponents` feature) is enabled.
### Why?
Previously, users could return an empty array (`[]`) from
`generateStaticParams` to indicate a route should be treated statically
without providing specific parameter values. This pattern has a critical
issue with Cache Components:
**The Problem:**
- With Cache Components enabled, accessing `params` is treated as a
dynamic API usage
- When `generateStaticParams` returns empty results, Next.js cannot
perform build-time validation to detect if the route accesses other
dynamic APIs (like `await cookies()`, `await headers()`, or `await
searchParams`)
- This means users could successfully build routes that would fail at
runtime with dynamic API errors
**The Solution:**
- By requiring at least one parameter value, we can execute the route
during build time with real params
- This allows us to validate that the route doesn't make additional
dynamic API calls that would cause runtime failures
- Build-time validation catches configuration errors early, before
deployment
### How?
- Modified `buildAppStaticPaths` in
`packages/next/src/build/static-paths/app.ts` to check if PPR is enabled
and throw error when `generateStaticParams` returns empty array with
Cache Components enabled
- Added comprehensive error documentation at
`errors/empty-generate-static-params.mdx` with migration options
Migration paths provided in error documentation:
1. Return at least one real param (recommended)
2. Use placeholder params (not recommended, bypasses validation)
The breaking change is acceptable because `cacheComponents` is still
experimental and only available in canary releases.
### Related
- Addresses discrepancy discovered with
https://github.com/vercel/next.js/discussions/84925.
- Fixes https://github.com/vercel/next.js/issues/84801
In Dev, to ensure the component metadata that powers React DevTools
accurately reflects the cached, prerendered, or dynamic nature of Server
Components, Next.js ensures that any caches encountered during the
prerender are warm before streaming.
However when users have chrome devtools open with "disable caches" or
when a hard refresh is performed requests are made with a cache header
that instructs Next.js to bypass all server caches. In these cases every
request will always have empty caches and thus the entire request will
block on the time it takes to fill all caches. It isn't reccomended to
typically disable cache while developing with Next.js because it is even
more aggressive than the cold cache scenario real users would encounter
with a production deployment. But there are some reasons why it is
legitimate, for instance when you want to force any latent caches in
memory to by skipped. When this happens Next.js will now skip cache
warming to ensure the render is streamed quickly. We will also warn in
the console that the request did not have caches warmed up and Component
Metadata in React DevTools won't accurately reflect which components are
cacheable and prefetchable.
In the future we will also show this state in the Next.js devtools UI so
it is clearer you are operating in this mode without having to read a
warning log in the console
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.
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 <[email protected]>
> [!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
### 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.
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.
This does not add any validation but it makes the interface for
prerender match out intended API shape when validation is landed
---------
Co-authored-by: Janka Uryga <[email protected]>
This PR removes the deprecated sync access to Dynamic APIs.
- Removed UnsafeUnwrapped* types.
- Replaced `as unknown as UnsafeUnwrapped ` type casts to `as any` for
dev warning.
- Removed tests that expected sync access to not error.
- Removed `UntrackedExotic` functions.
- Modified tests that were accidentally doing sync access.
- Updated warnings to emphasize that it is a Promise and must be
awaited.
- Removed paragraph that states access is allowed from
`errors/sync-dynamic-apis.mdx`.
---------
Co-authored-by: Josh Story <[email protected]>
We have found many Next.js users are confused why images keep
revalidating so frequently (increasing cpu and cost).
The reason is usually that their upstream source images are missing the
`cache-control` header and thus fallback to the 60 second revalidation
default. This its not a great default since most images don't change
frequently.
This PR is a breaking change to bump the `images.minimumCacheTTL` config
from 60 (1 min) to 14400 (4 hours).
Why 4 hours? Because its long enough to take advantage of the durable
cache, but short enough that changing or deleting the upstream src image
will take effect on the same day.
For advanced use cases where images are changing frequently, developers
can change this behavior back by reducing `images.minimumCacheTTL` to a
lower value.
This removes the env gate that opted into old behavior. Without
explicitly setting `scroll-behavior: 'smooth'` on the document, Next.js
will not attempt to programmatically disable smooth scrolling when
performing certain router events. This is a performance optimization in
all cases that do not care about smooth scroll.
The `legacyBehavior` prop of the `Link` component has been deprecated
since #77473. For Next.js 16, we're finally removing support for it.
Consequently, we're also removing support for the `passHref` prop, which
was only useful in conjunction with the `legacyBehavior` prop.
A [codemod is
available](https://nextjs.org/docs/app/guides/upgrading/codemods#new-link)
to help you automatically upgrade your codebase.
reverts #77473
---------
Co-authored-by: Sebastian Sebbie Silbermann <[email protected]>
What?
This PR updates the dependency "prettier" from version 3.2.5 to version
3.6.2. It also modifies other scripts by using the pnpm run prettier-fix
after updating the dependency.
Why?
This is updated to benefit from the changes and fixes introduced in the
newer versions of prettier, from versions 3.3 to 3.6.
How?
The package has been updated using pnpm install prettier@latest, and the
files other than package.json and pnpm-lock.json have been modified
using the script pnpm run prettier-fix.
This PR does only have formatting changes introduced by the updated
dependency
This PR is the same as #82719 , with fixes implemented to prevent
prettier to modifiy symlink files
Currently we error if you cannot produce a shell unless you have a
Suspense boundary above the root. This is fine for normal IO but sync IO
like Math.random() and new Date() have much more significant bad
consequences for prerendering. Instead of treating these errors as
another flavor of "must have a shell" validation we should instead treat
them like they must be guarded behind something else dynamic like `await
connection()`.
In addition to unconditionally erroring for Sync IO in Server Components
when prerendering this change also removes the Sync IO warning for
runtime prefetches. This is because at the moment there is no way to
debug these errors in dev. In the future we will add validation for
prefetches and need to add back in some ability to warn for these cases
but until then we will leave this case as a silent deopt.
Add a warning to Next.js 15.5 to prepare for Next.js 16 when
`images.localPatterns` is undefined and the user attempted to optimize a
`src` image with a query string, such as
```jsx
<Image src="/api/user?id=1" width="50" height="50" />
```
## What?
Rename `experimental.dynamicIO` to `experimental.cacheComponents` across
the Next.js codebase.
## Why?
We're going to be merging the functionality of the `ppr`, `dynamicIO`
and `useCache` experimental flags into the singular `cacheComponents`
flag to reduce complexity of the codebase and simplify adoption for
users wanting to experiment with experimental features.
## How?
- Renamed the configuration option from `experimental.dynamicIO` to
`experimental.cacheComponents`
- Added deprecation handling with automatic migration for the old option
name
- Updated all documentation, tests, and internal references
- Updated Rust code in SWC transforms and Turbopack
- Maintained backward compatibility with deprecation warnings
NAR-158
**What:**
`layout-router` currently forces style recalculation on every navigation by manipulating the `scroll-behavior` CSS property on the `<html>` element. This would impact most navigations, even though most don't use smooth scrolling
**Why:**
To prevent smooth scrolling during router navigation (which can feel janky), Next.js temporarily resets `scroll-behavior` to `auto`, then restores the original value (#40642). While this solves the UX issue, it causes performance overhead for the vast majority of users who don't have smooth scrolling configured.
**How:**
This PR introduces an optimization that checks for a `data-scroll-behavior="smooth"` attribute before manipulating styles. Only users who explicitly opt into smooth scrolling will experience the style recalculation.
- The existing behavior is preserved by default
- Opt-in to the new behavior by setting `experimental.optimizeRouterScrolling: true` in Next.js config
- When smooth-scroll is detected on the document, a development warning is logged to notify that the default behavior will be changing in an upcoming major.
When you use sync IO in the client in a way that needs to be fixed we
currently still just provide you with the explanation for server
components. The fixes when sync IO happens in the client are not the
same as when they happen in a server component so this update adds
client specific documentation for these situations.
Namely, the key difference is that on the server you can add caching
through "use cache" and this is not available to you in the client. sync
IO in general is (going to be) allowed in client components broadly as
long as Next.js has a fallback UI to prerender. This means that "fixing"
sync IO access in the client will usually be solved by wrapping in a
Suspense boundary. The alternative is to move the sync IO out of render
or move it to the server where it can be cached.
