Guidance for those who don't customize their own not-found page, pages
router's 404, etc, because the defaults honor the system style, not any
app-level theme settings.
## 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 -->
This PR cleans up small documentation and error-page issues: correct
TypeScript spelling where it was written as “Typescript”, use the proper
GitHub label in links, fix the MDN URL for `Map.prototype.values` in the
middleware upgrade guide.
No runtime or API behavior changes.
Remove
/02-pages/03-building-your-application/03-data-fetching/03-forms-and-mutations.mdx
- which is not reachable from the site, because it has been replaced by
the https://nextjs.org/docs/pages/guides/forms guide.
The Cloudinary URL for the overlay screenshot
(`assets.vercel.com/image/upload/v1645118290/docs-assets/static/docs/error-handling/overlay.png`)
404s. The line above it had a `{/* TODO UPDATE SCREENSHOT */}` comment,
so this was already flagged as known-stale.
Removes the broken image and its `"Here is an example of an overlay:"`
intro line. The paragraph above still explains what the overlay is, so
the page reads cleanly without the screenshot. If someone produces a
fresh screenshot later, restoring the markdown with an updated URL is a
one-line change.
### Affects
-
`nextjs.org/docs/pages/building-your-application/configuring/error-handling`
(stable, on next stable cut)
-
`nextjs.org/docs/canary/pages/building-your-application/configuring/error-handling`
(canary)
### Older versions
The same broken URL is present in v13/v14/v15 of the docs (synced from
the corresponding release tags). Backport is a separate call for
maintainers.
## 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
## What
Rename the HMR WebSocket path from `/_next/webpack-hmr` to `/_next/hmr`.
## Why
The `webpack-hmr` name is a leftover from when webpack was the only
bundler. Now that Turbopack is the default bundler for both `next dev`
and `next build`, the path name is misleading. The generic `/_next/hmr`
better reflects that this endpoint is bundler-agnostic.
## Changes
- **Client source** (`page-bootstrap.ts`, `web-socket.ts`): updated the
WebSocket connection path
- **Server** (`router-server.ts`): updated the HMR request detection
path
- **Turbopack** (`turbopack-dev-server/src/lib.rs`): updated the
fallback WebSocket path check
- **Tests**: updated all test files referencing the old path
- **Docs** (`version-12.mdx`): added a note that the path was renamed to
`/_next/hmr` in Next.js 16, while keeping the original v12 examples
intact
## 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>
### What?
Small improvements to the Forms guide for consistency and clarity.
### Why?
Some examples didn’t fully match the recommendations in the guide (e.g.
HTML validation), and there was a minor inconsistency between
`event.target` and `event.currentTarget`. This update keeps the examples
aligned and easier to follow.
### How?
- Added `required` to relevant input examples
- Standardized usage of `event.currentTarget`
- Made minor wording refinements for clarity
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
The second and third bullet points in the 'Good to know' callout were
incorrectly placed outside the blockquote, breaking the visual grouping
on the rendered documentation page.
<!-- 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: Andrew Damelio <andrewdamelio@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?
[`next-intlayer`](https://intlayer.org/doc/environment/nextjs) is an
i18n library that adopts a per-component approach to manage multilingual
content in a next.js application.
### Changes
- Fix doc related to page-router documentation,
- And add App Router realted doc.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
## For Maintainers
### What?
Changed the API route example in the documentation to use `.ts` file
extension for the TypeScript example since it uses TypeScript types.
Added a JavaScript example with `.js` extension using the `switcher`
prop to provide both TypeScript and JavaScript variants in the docs.
### Why?
The existing example used a `.js` extension but included
TypeScript-specific type annotations which is inconsistent and could
confuse users.
Providing both TypeScript and JavaScript examples improves clarity and
usability, catering to a broader audience.
### How?
- Updated the filename in the TypeScript example code block to
`pages/api/hello.ts`.
- Added a parallel JavaScript example code block with
`pages/api/hello.js` using the `switcher` property.
- Ensured both examples show equivalent handler logic with and without
type annotations.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
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>
We are dropping amp support in an upcoming major. This adds a warning
for using these configuration options and updates the docs with the
warning.
---------
Co-authored-by: Sebastian "Sebbie" Silbermann <sebastian.silbermann@vercel.com>
Joseph