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>
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.
- Document the experimental persistent caching flag
- Document the gap with the `innerGraph` optimization
- Document the css module ordering issue
- Document the persistent caching gap
Will wait to submit this until the when we publish the release.
Previously, we asked users if they want to use Turbopack for `next dev`.
Now, we ask if they want to use Turbopack, and if they do, we use it for
both dev and build. It’s also listed as `(recommended)` like App Router.
Test Plan: `pnpm build`, `./node_modules/.bin/create-next-app
~/path/to/app`. Choose the Turbopack option. Verify the app uses
Turbopack for both dev and build.
## 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>
The PR fixes issues in two different guides.
### PPR
In PPR, the code for jsx and tsx versions should use the language
switcher. Currently, these are displayed below each other in the guide
which seems unintentional.
### ISR
This change fixes multiple issues:
**fixes in the example:**
the example currently does not match the text below (_Here's how this
example works:_). It says:
> If /blog/26 is requested, Next.js will generate and cache this page
on-demand
that is of course not correct because there are only 25 blog posts
returned from the API. No blog post data is returned for `/blog/26`,
making this example wrong and confusing.
By slicing the posts and supplying only 24 of 25 blog posts for static
generation during the build process, the guide becomes much more
explicit - the 25th blog post can be used for inspecting the workings of
the on-the-fly generation and caching. Turning `dynamicParams` to
`false` or `true`, one can now truly test this behaviour with the 25th
blog.
Second, the same example in Pages Router docs includes:
> return { paths, fallback: false }
In this case, again, this part below:
> If /blog/26 is requested, Next.js will generate and cache this page
on-demand
is incorrect. When setting `fallback` to `false`, the page is never
generated on-demand and returns 404 instead as there is no 26th blog
post in the fetched data. So the fix changes the value of `fallback` to
`blocking`, to mirror the App Router's `dynamicParams` value in the
guide. This makes is more consistent and, more importantly, reproducible
example.
**clarifying the on-demand section:**
The sections dedicated to **on-demand revalidation** do not currently
mention that revalidation works differently from the time-based one. One
may assume the first request after on-demand revalidation returns stale
data (just like time-based).
But that's not true, the next request after on-demand revalidation (with
Server Actions for example) generates the content on-the-fly and returns
fresh data right away. It wasn't clear to me so I tested it myself and
was surprised (and happy) that it is this smart. I think it's very
important to clarify this distinction in the guide.
-----
I hope this makes sense. I'm quite responsive these days and will change
it based on your feedback (if any). Thanks!
<!-- 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
### Adding or Updating Examples
- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
### 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>
# Improve Content Security Policy Documentation
This PR comprehensively improves the Next.js Content Security Policy
(CSP) documentation to address community feedback from Reddit and GitHub
discussions about gaps in the current documentation.
## Changes Made
### 1. Enhanced Nonce Flow Explanation
- Added detailed section explaining how Next.js automatically detects
and applies nonces during server-side rendering
- Clarified the 3-step process: middleware generation → Next.js
extraction → automatic application
- Explained that developers don't need to manually add nonces to every
script tag
### 2. Static vs Dynamic Rendering Documentation
- Added comprehensive section explaining performance implications of
using nonces
- Documented that nonces force all pages into dynamic rendering
- Explained trade-offs: slower page loads, increased server load, no CDN
caching
- Added guidance on when to use nonces vs alternatives
### 3. Experimental SRI (Subresource Integrity) Documentation
- Documented the experimental `sri.algorithm` configuration option
- Explained hash-based CSP as an alternative to nonces that preserves
static generation
- Included configuration examples and benefits/limitations
- Noted that SRI is webpack-only, App Router only, and experimental
### 4. Development vs Production Considerations
- Added section addressing environment-specific CSP requirements
- Documented need for `'unsafe-eval'` in development for HMR
- Provided conditional CSP examples based on NODE_ENV
### 5. Comprehensive Troubleshooting Section
- Added solutions for error pages that don't work with strict CSP
- Documented third-party script integration with CSP
- Included common CSP violation fixes
- Added examples for both App Router and Pages Router
### 6. Practical Examples
- Static site with hash-based CSP using SRI
- Dynamic site with nonce-based CSP
- Mixed approach for different page types
- Environment-aware CSP configuration
### 7. Enhanced Pages Router Documentation
- Added `_document.tsx` nonce access example
- Improved `getServerSideProps` examples
- Added third-party script integration examples
## Community Feedback Addressed
This PR directly addresses the Reddit thread feedback about:
- ❌ "it is not clear that the nonce is then picked up by the rest of the
pages" → ✅ Added detailed nonce flow explanation
- ❌ "it is not clear that the pages therefore are not statically
generated anymore" → ✅ Added static vs dynamic rendering section
- ❌ "The solution of being able to provide the sha256 hashes... is not
supported, and it is not mentioned in the documentation" → ✅ Added
experimental SRI documentation
- ❌ Poor documentation of strict CSP implementation → ✅ Added
comprehensive examples and troubleshooting
## Technical Details
- **File Modified**: `docs/01-app/02-guides/content-security-policy.mdx`
- **Lines Added**: 642 insertions
- **Maintains**: Existing documentation structure and Next.js
conventions
- **Supports**: Both App Router and Pages Router with appropriate
switcher components
## Testing
- Verified all code examples use correct Next.js APIs and patterns
- Ensured documentation follows existing Next.js docs structure
- Confirmed all referenced configuration options exist in the codebase
- Validated that experimental features are properly marked as such
---
**Link to Devin run**:
https://app.devin.ai/sessions/e7e5fa95dc0146b3ab79aac72c53ed13
**Requested by**: lee@vercel.com
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: lee@vercel.com <lee@vercel.com>
Co-authored-by: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
## What?
Added a new "React Developer Tools" section to the debugging
documentation.
## Why?
This PR resolves#82308 which highlighted that React DevTools - a
fundamental debugging tool for React applications - was missing from
Next.js debugging documentation.
Since the Next.js framework is built on React, React DevTools is crucial
for:
- Inspecting component hierarchies
- Debugging state and props
- Identifying performance issues
- Understanding application structure
## How?
Inserted a concise section between "Client-side code" and "Server-side
code" in
[docs/01-app/02-guides/debugging.mdx](https://github.com/vercel/next.js/blob/canary/docs/01-app/02-guides/debugging.mdx):
- Introduces developers to the essential React debugging tool and its
key features
- Direct users to the corresponding React documentation
### Checklist: Improving Documentation
- [x] Ran `pnpm prettier-fix` to ensure proper formatting
- [x] Followed the Docs Contribution Guide:
https://nextjs.org/docs/community/contribution-guide
Closes#82308
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
<img width="591" height="132" alt="image"
src="https://github.com/user-attachments/assets/9c9c64fe-4095-4127-a893-1c12426d9700"
/>
- When I first read the explanation, it felt as if `redirect` couldn’t
be used in client components.
- Also, when clicking the `Server Components` link, it leads to the
`Server and Client Components` page.
- To indicate that `redirect` can be used in both `server and client
components`, rename the hyperlink text in the `redirect.mdx` file.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Kaung Min Khant