This PR improves the meta descriptions on certain pages.
<!-- 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
We encourage you to use AI to assist you in researching, creating, and
reviewing changes. However, you must review and deeply understand the
contributions you are making. For this reason, **pull request
descriptions from external contributors must be written by a human**.
### 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
### Signed commits
- This repository requires verified commit signatures on protected
branches.
- If this pull request is blocked for unsigned commits, re-sign the
commits and force-push the branch.
- A `Signed-off-by` line in the commit message is not enough.
## 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 #
-->
Supersedes https://github.com/vercel/next.js/pull/91848
`catchError` works in both the App Router and Pages Router, but its API
reference only documented the App Router behavior. This adds a Pages
Router reference backed by the same canonical document and scopes the
content that differs between routers.
The Pages Router examples use `reset()` because `retry()` is App
Router-only, omit App Router-only navigation behavior, and use Pages
Router component paths. The existing App Router guidance and shared API
reference remain unchanged.
<!-- NEXT_JS_LLM -->
## What
Updates docs links whose targets have moved. Found by an automated docs
link audit: every old URL below currently serves a `308` (permanent
redirect), so readers take an extra hop and the links rot as redirect
maps are pruned.
Each replacement is the **final `200` URL** of the redirect chain
(verified with `curl -sIL`), not just the first hop. Only the path
component was rewritten — scheme, host, query strings
(`?utm_source=...`) and fragments are untouched.
| Old path | Now points at |
| --- | --- |
|
`vercel.com/docs/concepts/functions/edge-functions/og-image-generation`
| `/docs/og-image-generation` |
| `vercel.com/docs/frameworks/nextjs` |
`/docs/frameworks/full-stack/nextjs` |
| `vercel.com/docs/observability/otel-overview` |
`/docs/tracing/instrumentation` |
| `vercel.com/docs/concepts/observability/otel-overview/quickstart` |
`/docs/tracing/instrumentation` |
| `vercel.com/docs/edge-config/get-started` |
`/docs/global-config/get-started` |
| `vercel.com/docs/functions/vercel-functions-package` |
`/docs/functions/functions-api-reference/vercel-functions-package` |
| `vercel.com/docs/edge-network/overview` | `/docs/cdn` |
| `vercel.com/docs/storage/vercel-blob` (×4) | `/docs/vercel-blob` |
| `vercel.com/docs/storage/vercel-blob/server-upload` |
`/docs/vercel-blob/server-upload` |
| `vercel.com/docs/storage/vercel-blob/client-upload` |
`/docs/vercel-blob/client-upload` |
| `vercel.com/docs/concepts/image-optimization` |
`/docs/image-optimization` |
| `nextjs.org/docs/app/building-your-application/rendering` |
`/docs/app/getting-started/caching` |
The four Pages Router pages flagged by the audit (`deploying`,
`guides/instrumentation`, `guides/open-telemetry`, `guides/redirecting`)
share their source with the App Router versions via frontmatter
`source:`, so fixing the App Router files covers them.
## One link worth a reviewer's eye
In `use-client.mdx`, the client-server **boundary** link pointed at
`/docs/app/building-your-application/rendering#network-boundary`. That
path 308s to `/docs/app/getting-started/caching`, which is what this PR
uses — but the redirect target is topically unrelated to the
client-server boundary, and no `#network-boundary` heading exists on it
(or anywhere else in `docs/`). If you'd prefer,
`/docs/app/getting-started/server-and-client-components` is the closer
page and I'm happy to switch it (the anchor would have to be dropped
either way).
## Also checked: `viewTransition`
The `next-config-js` reference index on nextjs.org still lists an entry
linking to
`/docs/app/api-reference/config/next-config-js/viewTransition`, which
404s. No change is needed in this repo: that page was intentionally
deleted in 28a9465d4 ("docs: view transitions guide — skill section,
source-audit fixes, flag-removal docs", #96097) as the docs half of the
`experimental.viewTransition` flag removal (#96098), and the guide now
states that view transitions work with no configuration. There is no
surviving config option to repoint at, and no link to it remains
anywhere in `docs/` or `packages/*/src` on `main` — the stale index
entry comes from the nextjs.org versioned (v15) nav manifest, outside
this repo.
## Verification
- `prettier --check` passes on all changed files.
- `alex` (`lint-language`) reports only pre-existing prose warnings on
untouched lines.
- No `next.js` build was run; this is a docs-only, path-only change.
▲ Created with [Vercel
devbox](https://vercel.com/vercel/~/sandboxes/devboxes/1us5zdxyl2nk5ccodexgd9w3f6k2)
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
## Summary
- add `experimental.useTypeScriptCli` so projects can explicitly run
their local `tsc` during `next build`, including TypeScript 7 while the
legacy JavaScript API is unavailable
- preserve the TypeScript API backend as the default, with TypeScript
6-compatible dependency installation and actionable TypeScript 7
migration guidance
- load effective compiler metadata through `tsc --showConfig`, preserve
inherited path origins, stream native diagnostics, redirect incremental
state, and forward worker termination to the compiler process tree
- document the experimental behavior and cover TypeScript 6/7, both
bundlers, raw diagnostics, full-project checking, dependency selection,
and cleanup
## Demo
```
pnpm build
> cna@0.1.0 build /Users/timneutkens/projects/sandbox/cna
> next build
▲ Next.js 16.3.0-canary.81 (Turbopack)
✓ Running next.config.ts took 23ms
- Cache Components enabled
- Experiments (use with caution):
✓ useTypeScriptCli
Creating an optimized production build ...
✓ Compiled successfully in 3.9s
Running TypeScript ...
app/page.tsx:8:3 - error TS2322: Type 'string' is not assignable to type 'number'.
8 return count++ + "abc";
~~~~~~
Found 1 error in app/page.tsx:8
Failed to type check.
Next.js build worker exited with code: 1 and signal: null
ELIFECYCLE Command failed with exit code 1.
```
## Verification
- `pnpm test-start-turbo
test/production/app-dir/typescript-cli/typescript-cli.test.ts`
- `pnpm test-start-webpack
test/production/app-dir/typescript-cli/typescript-cli.test.ts`
- `pnpm test-start-turbo
test/production/ci-missing-typescript-deps/index.test.ts`
- `pnpm test-dev-turbo
test/development/typescript-native-preview/index.test.ts`
- `pnpm test-start-turbo test/production/typescript-basic/index.test.ts`
<!-- NEXT_JS_LLM_PR -->
## Summary
- move adapter implementation docs from
`app/api-reference/config/next-config-js/adapters` to
`app/api-reference/adapters`
- keep `adapterPath` as an entry page that points to the new adapters
section
- add matching Pages Router pointer docs under
`pages/api-reference/adapters`
- update existing docs links that referenced old `adapterPath#...`
anchors to the new adapters routes
## Move `adapterPath` from experimental to stable
Graduates `adapterPath` from `experimental.adapterPath` to a top-level
`NextConfig` option, following the same pattern used for
`cacheHandlers`, `cacheComponents`, `typedRoutes`, and other options
that moved out of experimental.
### Changes
- **Type definition** (`config-shared.ts`): Added `adapterPath` to
`NextConfig` interface, marked `ExperimentalConfig.adapterPath` as
`@deprecated`, moved default value to top-level in `defaultConfig`,
updated `NextConfigRuntime` and `getNextConfigRuntime`
- **Zod schema** (`config-schema.ts`): Added `adapterPath` to top-level
`configSchema`
- **Backward compat** (`config.ts`): Added
`warnOptionHasBeenMovedOutOfExperimental` call so existing
`experimental.adapterPath` configs still work with a deprecation
warning, updated `applyModifyConfig` to read from `config.adapterPath`
- **Runtime references**: Updated `build/index.ts`, `app-page.ts`,
`app-route.ts`, `pages-handler.ts` to use `config.adapterPath` /
`nextConfig.adapterPath`
- **Tests**: Updated 4 test fixture `next.config` files
- **Docs**: Updated app router doc (removed `version: experimental`
frontmatter, top-level config example), pages router doc title, and v16
upgrade guide
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>
## Description
This PR adds dedicated documentation pages for `useSearchParams` and
`useParams` hooks in the Pages Router documentation.
### Changes
- Added
`docs/02-pages/04-api-reference/03-functions/use-search-params.mdx`
- Added `docs/02-pages/04-api-reference/03-functions/use-params.mdx`
### Why
Both `useSearchParams` and `useParams` from `next/navigation` work in
the Pages Router, but this was not well documented. The only mention was
a brief note in the App Router docs and a migration section in the Pages
Router `useRouter` docs.
### What's Documented
For both hooks:
- Basic usage with the fallback UI pattern for handling `null` during
pre-rendering
- Return values and behavior differences from App Router
- Usage with `getServerSideProps` (where params are immediately
available)
- Examples for sharing components between App Router and Pages Router
For `useParams` specifically:
- Comparison with `router.query` (which includes both dynamic params and
query string params)
### Related Test
The existing test at `test/e2e/app-dir/params-hooks-compat` validates
that these hooks work in both routers.
This PR adds instructions on how to run and navigate the new turbopack
bundle analyzer to the existing [Optimizing package bundling guide
](https://nextjs.org/docs/app/guides/package-bundling).
Todo:
- [x] Embed video
- [x] Add image for import chain
---------
Co-authored-by: Luke Sandberg <lukesandberg@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Rich Haines <hello@richardhaines.dev>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
### What?
[ZenStack](https://github.com/zenstackhq/zenstack) is a toolkit built
above Prisma ORM for adding access control and other features. This
change adds one of its packages "@zenstackhq/runtime" to the default
list of "serverComponentsExternalPackages".
### Why?
The package is frequently used in Next.js route handlers and results in
false-positive errors with Next.js's bundler (likely caused by
dynamically `require` modules).
### How?
Add the package to the default external packages list.
---------
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
### What?
Adds `@alinea/generated` to the external package list
### Why?
[`Alinea`](https://github.com/alineacms/alinea) generates this package
at build time and it should not end up in a cache (much like the
`@prisma/client` package)
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
## 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>
> [!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?
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.
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>
`next/legacy/image` was introduced in Next.js 13 as way to allow
developers to upgrade from 12 to 13 with minimal effort.
Now that its been 3 years, its time to deprecate `next/legacy/image` in
Next.js 16 so we can remove it in a future version.
This will print a warning the first time the component is used.
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 option was renamed/stabilized from `experimental.turbo` to `turbopack` in 15.3.
The app router page title/path was correct, but pages router had the wrong thing.
Let me know if I should add a redirect for this somewhere?
As this lands and people learn about the new Route Props helpers, I
think we will have this period where the TypeScript snippets show the
manual typing, but in key places we introduce the helpers usage. We can
then follow up updating all TypeScript snippets showing a page, layout
or route, to use these.
---------
Co-authored-by: Ben Gubler <nebrelbug@gmail.com>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
## 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>
Joseph