## Summary
A systematic review pass over the App Router documentation
(`docs/01-app`, 281 MDX files) fixing clear-cut typos, grammar issues,
and technical inaccuracies — code samples, file names, and API
signatures that had drifted from the implementation in
`packages/next/src`.
The review ran four passes: an automated spell check with a triaged
allowlist, targeted grammar-pattern searches, structural checks
(frontmatter, code fences, link targets), and a technical-accuracy pass
over all getting-started pages plus high-traffic API reference pages,
with every suspected inaccuracy verified against the source before
editing. Only unambiguous issues were fixed; anything debatable was
deliberately left alone (e.g. the `/aboot` route in the typedRoutes docs
is an *intentional* invalid-route example, and the CLI docs table
intentionally mirrors the actual `--help` output).
Notable fixes:
- JSX examples now `await params`, matching the Promise-based API and
their TypeScript counterparts
- `generateStaticParams()` is now exported in samples so the convention
actually takes effect
- `<Link prefetch>` props table includes `"auto"`, matching the `boolean
| "auto" | null` type in `link.tsx`
- `Navigator.geolocation` casing, the canonical react.dev `"use client"`
link, and a missing `Link` import in the typedRoutes docs
- Mismatched or wrong `filename=` labels in TS/JS switcher pairs
(`form.mdx`, `mutating-data.mdx`, `css.mdx`) and a wrong
`generateStaticParams` anchor target
- ESLint monorepo example registers the plugin as `@next/next` so the
documented rule prefixes resolve
- Spelling/grammar: `emphaize`, `invokations`, `behaviour` → American
spelling, "setup" → "set up" as a verb (5×), "a RSC" → "an RSC",
`NextJS` → `Next.js`, a stray comma, and "a `opengraph-image.tsx`"
article plus its folder path
## Verification
- `cspell` over all 281 files in `docs/01-app`: 0 issues outside a
reviewed allowlist of product names, API identifiers, and intentional
example strings
- `prettier --check` (3.6.2, repo config): passes on all 19 changed
files
- Grammar-pattern and structure greps: clean
- Technical claims cross-checked against `packages/next/src` and
`packages/eslint-plugin-next`
- Docs-only change; no runtime code touched
<!-- NEXT_JS_LLM -->
<!-- fleet eeae4385-18f5-406d-915e-986961503ed2 -->
Co-authored-by: vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: Tobias Koppers <1365881+sokra@users.noreply.github.com>
- Adding
docs/01-app/03-api-reference/05-config/01-next-config-js/cacheMaxMemorySize.mdx
- Various use cache snippet fixes
- Break nuance for fetch default
- Point to correct turbopack cache flags
## Summary
- Fix wording in Link prefetch docs: `navigation's` -> `navigation`
- Fix wording in CRA migration guide: `clients components` -> `Client
Components`
## Why
These are user-facing documentation wording issues. This change improves
clarity and readability for readers following these guides.
## Scope
Docs-only changes. No runtime behavior changes.
Attribution: This change was originally authored by @Rezakarimzadeh98 in
#96998.
Co-authored-by: Reza Karimzadeh <r.karimzadeh1998@gmail.com>
With the latest GA changes, when using Cache Components with Partial
Prefetching:
> prefetch={true} turns on prefetching
These changes try to align around that idea.
- runtime prefetching guide is now about optimizing
- various changes in prose across docs
- even fix an error page for pages router, which had a broad title
---------
Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
## Summary
- update the Partial Prefetching adoption skill for the current runtime
prefetching model
- scope the Cache Components optimizer's runtime-prefetch limitation to
URL data
- preserve the optimizer pattern structure for URL data that cannot
move, with Partial Prefetching, targeted `<Link prefetch={true}>`, and
cached URL-data content as the requirements
- make the optimizer follow-up conditional: use targeted
`prefetch={true}` when the app already adopted Partial Prefetching,
otherwise recommend the PPF adoption skill for the broader shared App
Shell model
## Why
Andrew's Partial Prefetching work removes the old `allow-runtime`
route-config model. The skills should teach the current shape: Partial
Prefetching gives links a shared App Shell baseline with lower
duplicated prefetch cost, while `<Link prefetch={true}>` is reserved for
links where resolving URL-specific content before click is worth the
extra server work.
## Validation
- `git diff --check HEAD~1..HEAD`
- grep confirmed no `allow-runtime` / `force-runtime` references remain
in the changed Skill files
- attempted `skill-creator` quick validation, but the local Python env
is missing `yaml`
Removes the "allow-runtime" prefetch config, and turns its behavior on
implicitly wherever Partial Prefetching is enabled.
The original motivation for "allow-runtime" was to give apps more
control over server costs triggered by prefetches. Until a route
explicitly opts in, prefetches would only be served from the CDN, not
from the server. The problem, though, was it was very confusing to know
when to add or remove this configuration. The incentive for many apps
was to add it everywhere, with no clear signal for when to remove it.
Our updated thinking is that Partial Prefetching itself already provides
sufficient protection against runaway prefetching costs: per-link
prefetches only happen on Link components that explicitly opt in with
the prefetch prop.
The optimizations landed earlier in this stack also make allow-runtime
less necessary: on pages where all the content is statically renderable,
prefetches are served from the static cache and no runtime request is
ever issued; only a page that accesses non-static data is prefetched at
runtime.
The upshot of this decision is that runtime versus static becomes an
internal optimization; the same content gets prefetched regardless of
whether or how Next.js is able to optimize it.
## What
Follow-up to #95365. Documents adopting Partial Prefetching end to end:
- Restructures the [Adopting Partial Prefetching
guide](https://github.com/vercel/next.js/blob/canary/docs/01-app/02-guides/adopting-partial-prefetching.mdx)
around the two paths: enable `partialPrefetching` and audit every `<Link
prefetch={true}>` against a per-case decision table, or adopt
incrementally per route with the
[`instant-link-prefetch-partial`](https://nextjs.org/docs/messages/instant-link-prefetch-partial)
insight as the worklist. Adds `Auditing routes for URL data` and
`Prefetching URL data` sections.
- Adds the `remove-partial-prefetch` codemod, which strips the redundant
per-route `prefetch = 'partial'` exports once the flag is on while
preserving comments and other `prefetch` values.
- Adds the `next-partial-prefetching-adoption` skill that sequences the
guide for agents: audit, enable + codemod, URL-data sweep, verify,
optional runtime prefetching.
- Aligns the `instant-link-prefetch-partial` error page, `<Link>`
reference, glossary, and Interactive apps guide with the same prefetch
model.
## Why
With the flag on, `<Link prefetch={true}>` no longer delivers dynamic
content, and shell validation flags `params`/`searchParams` reads
outside `<Suspense>`. Adopters need one guide that sequences the audit,
the flag, and both insights, and an agent skill that follows it.
Stacked on #95365 (base: `codex/instant-shell-link-data`) since it links
to the `instant-shell-url-data` error page that PR introduces. GitHub
will retarget to `canary` when that merges.
<!-- NEXT_JS_LLM_PR -->
### What?
Three friction points found while running through the Partial
Prefetching migration on a Cache Components app:
- **`prefetch.mdx`** — added `'partial'`. It's a real value in the
framework but the docs page didn't list it.
- **`link.mdx`** — rewrote the `prefetch={true}` bullet so it's correct
on its own under Partial Prefetching, not only inside the callout below.
- **`adopting-partial-prefetching.mdx`** — restored the "Going further"
section and added a before/after migration example.
### Related
[#94798](https://github.com/vercel/next.js/pull/94798) — Insight surface
for the new `<Link prefetch={true}>` warning. Lands independently.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
- changes getting started -> caching
- new guide for instant navs
- new guide for runtime-prefetching (most pending stuff is here)
- x-refs between docs
- App Shell mentions in other docs (ISR w/ CC)
---------
Co-authored-by: Aurora Scharff <66901228+aurorascharff@users.noreply.github.com>
Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
## Summary
- add the missing `transitionTypes` entry to the `next/link` version
history table
- document that the prop was added in `v16.2.0`
## Testing
- not run (docs-only change)
<!-- NEXT_JS_LLM_PR -->
Some users have been confused by the relationship of
`images.remotePatterns` and `images.maximumRedirects` so lets document
it.
This behavior is expected since you might allowlist something like
`https://github.com/styfle.png` and that can redirect to whatever it
needs to redirect to (assuming maximumRedirects > 0). For example, it
currently redirects to
`https://avatars.githubusercontent.com/u/229881?v=4` but you can imagine
in the future if the redirect was changed, you wouldn't want your app to
break.
Regardless of redirects, the final response must be an image.
---------
Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>
This PRs unifies the caching story across the docs, making Cache
Components the happy path, while still providing guidance to users in
the old model. However, instead of explaining the old model and its
caching layers, we've created a new guide focusing on what APIs to use
and when.
This follow-up PR aligns terminology across the docs:
https://github.com/vercel/next.js/pull/90589
## IA updates
Getting Started section:
- Improves Getting Started progression:
- **Before:** CC → Fetching Data → Updating Data → Caching and
Revalidating (old and new model mixed)
- **After:** Fetching Data (Dynamic) → Mutating Data (Dynamic) → Caching
with CC (Prerendering) → Revalidating with CC.
- New: `caching.mdx` (CC-first)
- Structure:
- Enabling Cache Components
- Data vs UI-level caching
- Working with request time APIs
- Passing request values to cached functions
- Working with non-deterministic operations
- Working with synchronous operations
- How rendering works (PPR and static shell story)
- New: `revalidating.mdx` (CC-first)
- Explains how to use `cacheLife` and `cacheTag`
Guides Section:
- New: `caching-and-revalidating.mdx` (Previous Model)
- For users who are not using CC, includes `fetch` options and route
segment config
- Moves route segment config options that don't apply to CC from API
reference to this guide (for easy archiving in the future).
- New: `migrating-to-cache-components.mdx` (WIP)
- Del: `caching.mdx` 😌
## Terminology
We should remove caching layers from the docs. Users only needed to be
exposed to them when they were configured independently, but the new CC
APIs work across layers.
To make it easier to review this PR, I'm consolidating terminology and
fixing broken links in a new PR:
https://github.com/vercel/next.js/pull/90589
---------
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
This PR adds an LRU disk cache so that reads and writes from the Image
Optimization API will evict old entries based on the value of
`images.maximumDiskCacheSize` configuration.
The LRU ensures that cache reads bump the entry to the top so that they
don't get evicted - only the least recently used entries get evicted.
When `next start` is run, if there is an existing disk cache the we will
replay the files in order to populate the LRU and respect
`images.maximumDiskCacheSize` if it was changed.
If no configuration is provided, default to 50% available disk space.
Based on our metrics, the P99.9 for a source image is 47 MB so we can
adjust the default setting to be much lower (by changing from from 300
MB to 50 MB) in favor of reducing memory.
## Title
docs: add example for enabling both AVIF and WebP image formats
## Description
### What?
This PR enhances the image component documentation by adding examples
showing how to enable both AVIF and WebP image formats together in
`next.config.js`. It also updates the `image-component` example to
demonstrate this configuration.
### Why?
Currently, the documentation only shows examples for:
- WebP only (default): `formats: ['image/webp']`
- AVIF only: `formats: ['image/avif']`
However, many developers want to enable both formats together to:
- Prefer AVIF for browsers that support it (better compression, ~20%
smaller files)
- Fall back to WebP for broader browser compatibility
- Maximize image optimization across different browsers
This configuration is a best practice but wasn't clearly documented with
an example.
### How?
- Added example configuration `formats: ['image/avif', 'image/webp']` to
App Router image component documentation
- Added the same example to Pages Router (legacy) image component
documentation for consistency
- Updated `examples/image-component/next.config.js` to demonstrate the
configuration
- Added clarification that the order matters - Next.js uses the first
format in the array that the browser supports
### Changes Made
- `docs/01-app/03-api-reference/02-components/image.mdx` - Added AVIF +
WebP example
- `docs/02-pages/04-api-reference/01-components/image-legacy.mdx` -
Added AVIF + WebP example
- `examples/image-component/next.config.js` - Added formats
configuration
### Testing
- [x] Documentation changes only - no code changes
- [x] Verified examples are syntactically correct
- [x] Checked that formatting follows Next.js documentation guidelines
### Checklist
- [x] Run `pnpm prettier-fix` to fix formatting issues (if applicable)
- [x] Documentation follows the docs guidelines
- [x] Changes are clear and helpful for developers
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
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>
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>
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 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.
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.
**Summary**
This PR adds a note to the documentation clarifying the behavior when
using external or internal URLs (API Routes) as image sources with
Next.js Image Optimization.
This change addresses issue #82610.
**Details**
- Added a note explaining that, for security reasons, request headers
are not forwarded to API Routes or external URLs when Image Optimization
is used.
- Documented that if image data requires authentication, the
`unoptimized` property should be considered to disable Image
Optimization.
**Why**
Users may be confused when trying to load images from endpoints that
require authentication. This clarification helps developers understand
the limitation and how to handle such cases.
**References**
- [Vercel Changelog:
CVE-2025-57752](https://vercel.com/changelog/cve-2025-57752)
- [Next.js GitHub Issue
#82703](https://github.com/vercel/next.js/issues/82703)
---
resolves#82610
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
Co-authored-by: Steven <steven@ceriously.com>
The Image component's existing `priority` prop is confusing since its
not obvious what it does.
In order to improve clarity, we are introducing a `preload` prop and
deprecating the `priority` prop.
We also updated the dev warning to no longer suggest using this prop for
the LCP and instead use `loading="eager"`.
## Background
We have default allowlists for the `url` (localPatterns/remotePatterns
config) and `w` (imageSizes/deviceSizes config) but we don't have a
default allowlist for `q` (currently opt-in with via qualities config).
## What's changing?
BREAKING CHANGE: This PR is a breaking change that sets the default
allowlist to `qualities: [75]`, meaning that anything other than 75 is
invalid. Since most images don't set the quality prop and therefore
default to 75, most apps will be unaffected.
However, we can be even more gracious when users upgrade because we can
coerce the value automatically to 75 (or rather any value in `qualities`
allowlist). In dev, this will print a warning explaining why the prop
was not observed. This also works if you had `qualities` configured but
removed 75, since the closet matching value in the array will be used
instead.
Added `unoptimized` and `decoding` props to the props table (the table
at the top of the doc page).
I was looking for the `unoptimized` prop and thought it wasn't in this
page because I could not find it at the props table. I think it's better
included there since it's not deprecated. The same goes for `decoding`.
Added them with the same syntax as the rest values in the table.
Thanks.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
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 <sebastian.silbermann@vercel.com>
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
## Summary
Fix typos and spelling errors in various MDX documentation files to
improve clarity and consistency.
Documentation:
- Standardize 'cacheable' spelling across self-hosting guide
- Correct 'potentionally' to 'potentially' in image component references
- Fix 'unecessary' to 'unnecessary' in use-link-status guide
### Improving Documentation
- [x] Run `pnpm prettier-fix` to fix formatting issues before opening
the PR.
- [x] Read the Docs Contribution Guide to ensure your contribution
follows the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
This PR https://github.com/vercel/next.js/pull/80922 highlighted an
issue with the Link API reference.
Looking further into it I saw that we had mixed a few `AppOnly` +
`PagesOnly` tags, and needed a few more changes.
Add `contentSecurityPolicy` to Image Component in docs. Also follow up
in on the type in `image-config.ts` to use the updated docs.
---------
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Tobias Koppers
