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.
In the docs it says => ( The default caching behavior of fetch (e.g.,
when the cache option is not specified) is equal to setting the cache
option to no-store )
But when I code, I found that fetch default behaviour and setting the
cache option to no-store are different.
After building process ....
When changing routes. default is stored as cache. I see that because
there is no new network request when I change route. In setting the
cache option to no-store, it is making a new network request as soon as
i get back to the page.
so docs and real working one are mismatch.
I also provided how tested with pictures belows.
Please build... and check
Change routes...
<img width="545" height="371" alt="image"
src="https://github.com/user-attachments/assets/4931302f-b5ef-4016-b43d-cbbd790c1e11"
/>
<img width="601" height="409" alt="image"
src="https://github.com/user-attachments/assets/3f2b4a79-fa24-466f-8330-0dc8323b6c16"
/>
Fixes https://github.com/vercel/next.js/issues/83146
---------
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>
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>
Update installation guide, now we have Biome as an option to
create-next-app, and next lint is deprecated.
Also addresses: https://github.com/vercel/next.js/issues/82916
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Ben Gubler <nebrelbug@gmail.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
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>
## What?
Updated the documentation for `opengraph-image` / `twitter-image` to fix
the **Node.js runtime with local assets** example.
## Why?
The existing snippet did not type-check cleanly with Next.js 15+ and
could confuse developers.
This update improves developer experience by ensuring the snippet is
immediately usable and accurate.
## How?
- Reproduced the example in a fresh Next.js 15+ project.
- Updated the docs example to:
- Use `readFile` + Base64 encoding instead of invalid file URLs.
- Clarify that assets should be placed relative to the project root.
- Added an entry to **Version History** noting the update in v15.x.
## Checklist
- [x] Ran `pnpm prettier-fix`
- [x] Verified formatting & linting (`pnpm build && pnpm lint`)
- [x] Documentation guidelines followed
- [x] Example verified in a real Next.js 15 project
Fixes#75583 & #75625 (if considered same class of issue)
---------
Co-authored-by: Joseph <sephxd1234@gmail.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
## Add codemod to migrate from `next lint` to ESLint CLI
This PR introduces a new codemod `next-lint-to-eslint-cli` that helps
users migrate away from the deprecated `next lint` command to using
ESLint directly, in preparation for Next.js 16 where `next lint` will be
removed.
### What it does
The codemod automates the migration process by:
1. **Updating package.json scripts** - Replaces all `next lint` commands
with `eslint` equivalents
- Maps Next.js-specific flags (`--strict` → `--max-warnings 0`,
`--dir`/`--file` → paths)
- Preserves other ESLint-compatible flags
- Handles complex scripts with pipes, redirects, and multiple commands
2. **Managing ESLint configuration**
- Creates a new flat config (`eslint.config.mjs`) if none exists
- Updates existing flat configs to include Next.js rules
- Provides guidance for legacy configs that need manual migration
3. **Installing dependencies automatically**
- Adds required packages: `eslint`, `eslint-config-next`,
`@eslint/eslintrc`
- Detects and uses the project's package manager (npm/yarn/pnpm/bun)
- Falls back to manual instructions if installation fails
### Usage
```bash
npx @next/codemod@latest next-lint-to-eslint-cli .
```
### Example transformations
```json
// Before
{
"scripts": {
"lint": "next lint",
"lint:fix": "next lint --fix",
"lint:strict": "next lint --strict --dir src"
}
}
// After
{
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint --fix .",
"lint:strict": "eslint --max-warnings 0 src"
}
}
```
### Why this change?
- `next lint` is being deprecated and will be removed in Next.js 16
- ESLint v9+ flat config is becoming the standard
- Direct ESLint usage provides more flexibility and better ecosystem
compatibility
- Reduces Next.js maintenance burden of wrapping ESLint functionality
The codemod ensures a smooth transition path for existing Next.js
projects while following ESLint best practices.
- Rename `experimental.typedRoutes` to `typedRoutes`
- Remove old references to `typedRoutes` not working with Turbopack
- Remove unnecessary encoding of `typedRoutes` for bundlers
# Transition from `next lint` to explicit ESLint configs and add Biome support
## What?
This PR makes two major changes to Next.js linting:
1. **Transitions away from `next lint`**: `create-next-app` now generates explicit ESLint configurations instead of relying on the `next lint` command
2. **Adds Biome as a linter option**: Users can now choose between ESLint, Biome, or no linter during project setup
## Why?
**ESLint Transition**: Provides transparency (users see exact rules), better IDE integration, easier customization, and follows industry standards for explicit configuration.
**Biome Support**: Offers a faster, unified linting/formatting tool and gives users more choice in their developer experience.
## How?
### ESLint Configuration Generation
- Generates `eslint.config.mjs` files that extend `eslint-config-next` packages
- Includes proper ignores for build artifacts (`next-env.d.ts`, `.next/`, etc.)
- Package.json scripts call `eslint .` directly instead of `next lint`
- Maintains complete feature parity with current `next lint` behavior
### Biome Integration
- Added `--biome` flag and interactive prompt selection
- Generated `biome.json` configurations with Next.js and React domain rules
- Includes both `lint` and `format` scripts for Biome projects
### Linter Selection
Interactive prompt offers: **ESLint** (comprehensive rules), **Biome** (fast with fewer rules), **None** (skip linter)
### Deprecation
Added deprecation warning to `next lint` command (removed in Next.js 16)
## Testing
Added comprehensive test suites for both ESLint and Biome configuration generation across all template variants.
This change modernizes Next.js linting while providing users with more choice and transparency.
Lee Robinson