### What?
Move persistent caching for `next build` into a separate config option: `turbopackPersistentCachingForBuild`.
And `next dev` to `turbopackPersistentCachingForDev`.
https://github.com/vercel/next.js/pull/77850 moved `experimental.turbo`
option to `turbopack`, but `moduleIds` is intended for debugging, in
line with `turbopackSourceMaps` and `turbopackMinify`, so move to
`experimental.turbopackModuleIds`.
- In development, it's "named" by default, and making it "deterministic"
breaks HMR.
- In production, it's "deterministic" by default, and making it "named"
blows up bundle sizes and exposes your internal project structure in the
module ID strings.
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.
## Documentation Update
This PR improves the dynamic routes example in the
`project-structure.mdx` page.
### Changes
- Updated catch-all segments example:
- Before: `/shop/clothing/shoes`
- After: `/shop/clothing`
- Adjusted follow-up examples for consistency:
- `/shop/a`, `/shop/a/b` → `/shop/clothing`, `/shop/clothing/shirts`
### Why
- Provides a clearer and more intuitive demonstration of how catch-all
segments work.
- Keeps the example consistent with other dynamic routes documentation.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
In error messages and in docs for `'use cache'` and related APIs, we now
guide users to the `experimental.cacheComponents` config instead of
`experimental.useCache`.
closes NAR-410
Follow up to https://github.com/vercel/next.js/pull/83246#discussion_r2366553689
Discussed this with @lukesandberg and we can't find a place where it would be very useful, it seems it might've been useful with the old builtin condition syntax (which I removed).
It also looks like maybe I forgot to actually wire this up to anything? Whoops. Whelp, now it's gone.
~I'm looking for review/feedback, but **DO NOT MERGE UNTIL NEXT 16.0 IS RELEASED.** These APIs are not available on 15.5, and merging it now would be confusing to users. If you want to try it out, use a recent canary release.~ I've been informed that docs are not currently tracking canary, so this is safe to merge.
Documented the new configuration syntax added in https://github.com/vercel/next.js/pull/82857 that should ship with Next 16.0.
## Rendered
<details>
<summary>Toggle</summary>
<img src="https://app.graphite.dev/user-attachments/assets/b2404001-6e3f-47c9-9704-160fcfb1438d.png" width=1000>
</details>
Without the `| null`, the following error appears during compilation:
```
TS2322: Type RefObject<HTMLDivElement | null> is not assignable to type RefObject<HTMLDivElement>
Type HTMLDivElement | null is not assignable to type HTMLDivElement
Type null is not assignable to type HTMLDivElement
```
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
- Added a Note to the Middleware docs explaining that when
`pageExtensions` are customized (e.g. `.page.ts`), the Middleware file
should be named `middleware.page.ts` or `middleware.page.js`.
- Updated wording so `middleware.ts/js` is described as the default
filename, not a strict requirement.
<!-- 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?
-Added a callout note to middleware.mdx stating that if pageExtensions
is customized (e.g., .page.ts), the Middleware file should also match
(middleware.page.ts/js).
-Updated the language from “must” → “default is” for filename clarity.
### Why?
-Developers customizing pageExtensions were misled by the existing docs,
which implied middleware.ts/js was always required.
-This PR prevents confusion when Middleware isn’t recognized after a
pageExtensions change.
### How?
Edited docs/app/api-reference/file-conventions/middleware.mdx.
Inserted a > **Note** block right after the paragraph explaining where
to create the middleware file.
Closes NEXT-
Fixes#84008
-->
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
We have dropped the example linked in this page. I'll re-evaluate later
if the section is still enough for a dev to understand how to set CORS
related headers.
### What?
This PR fixes a missing comma in the function parameter in
`03-api-reference/03-file-conventions/layout.mdx`.
The comma between `children` and `params` parameters was missing in the
documentation example, showing incorrect syntax.
### Why?
The missing comma in the documentation example shows invalid
JavaScript/TypeScript syntax.
### How?
- Added missing comma after `children` parameter .
**Before:**
```tsx filename="app/dashboard/[team]/layout.tsx" switcher
export default async function Layout({
children
params,
}: {
```
**After:**
```tsx filename="app/dashboard/[team]/layout.tsx" switcher
export default async function Layout({
children,
params,
}: {
children: React.ReactNode
```
This PR adds docs for using Node.js native TS resolver for
`next.config.ts`. It states:
- Supports Node.js native TS resolver
- Why use it
- How to use it
- Restrictions
- Why use `next.config.mts`
I didn't mention how much it's faster compared to the legacy resolver
(~68% faster in the hello world app -
[link](https://github.com/vercel/next.js/pull/83240)) because the
experience may vary for users.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Abdón Rodríguez <a@abdonrd.com>
Make a couple of clarifications:
- type resolved by the helpers
- ways to narrow down to a narrower union
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Rich Haines <hello@richardhaines.dev>
<!-- 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? Removed link
### Why? To maintain text consistency. There are four includes of
'browser’s history stack' and two of them contain link with different
style.
### How?
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
[`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>
Adds the `bun add server-only` command to the data security guide.
This change adds the missing Bun package manager example to the
`docs/01-app/02-guides/data-security.mdx` file, ensuring consistency
with other documentation sections.
Fixes#83734
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
fix _nextjsDevtools csp error which happens in development environment
after enabling csp and following the current documents.
Full Error:
- Refused to apply inline style because it violates the following
Content Security Policy directive: "style-src 'self'
'nonce-YmYyMTZmYTQtMzgxNy00ZjYwLWIwMGQtYjBmYjJjNGYzZWQ1'
'unsafe-inline'". Note that 'unsafe-inline' is ignored if either a hash
or nonce value is present in the source list.
<!-- 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: Joseph <joseph.chamochumbi@vercel.com>
**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"`.
In previous docs versions, while not explicitly stated, it was rather
clearer that middleware has its own runtime.
Also, people who have used bundle-analyzer would for example be familiar
with the 3 bundles, or those who have worked with
`next.config.js`/instrumentation would understand that there's some
different runtimes at play going on there, but those who exclusively
work with middleware might still miss on this detail.
---------
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Certain relative links were absolute, which renders them with the ->
external arrow - might have been a decision per case, but AFAIK, this is
only helpful for those links that are now redirecting to other content
## 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.
Tim Neutkens
