- 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>
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>
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>
## Improving Documentation
Updated the doc to reflect the API signature of `cacheTag`, which takes
one or more string values.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
## Improving Documentation
Updated the `Dashboard` component to be an `async` function to properly
`await` the session verification process. This change ensures that the
user role is retrieved correctly from `session` before rendering the
component.
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
### What?
Fix the signatures of `useMDXComponents`.
### Why?
The `useMDXComponents` function is always called without any arguments.
It’s also always supposed to be a named export, not a default export.
It’s also called during render. Defining React components during render
is an anti-pattern. All components that were previously defined inside
of `useMDXComponents`, are now defined outside of the function.
### How?
Manual fixes.
---------
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
## What?
Rename `experimental.dynamicIO` to `experimental.cacheComponents` across
the Next.js codebase.
## Why?
We're going to be merging the functionality of the `ppr`, `dynamicIO`
and `useCache` experimental flags into the singular `cacheComponents`
flag to reduce complexity of the codebase and simplify adoption for
users wanting to experiment with experimental features.
## How?
- Renamed the configuration option from `experimental.dynamicIO` to
`experimental.cacheComponents`
- Added deprecation handling with automatic migration for the old option
name
- Updated all documentation, tests, and internal references
- Updated Rust code in SWC transforms and Turbopack
- Maintained backward compatibility with deprecation warnings
NAR-158
## What?
Adds support for `remarkPlugins: ['remark-gfm']` and `rehypePlugins:
['rehype-slug']`.
Previously you had to nest an array like `remarkPlugins:
[['remark-gfm']]` but that's a bug, that case is only for passing
options. Directly passing the string without options should be allowed.
This PR implements that.
### What?
Updated the documentation to clarify that App Router requires manual
locale handling through dynamic route segments and middleware, with
examples showing how to implement i18n redirects correctly.
### Why?
The App Router doesn't use the i18n configuration in next.config.js like
the Pages Router does.
Closes NEXT-
Fixes#81227
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Joseph <sephxd1234@gmail.com>
What?
This PR updates the Page component example in
05-server-and-client-components.mdx to use Promise-based params as
recommended in the Next.js 15 documentation.
Why?
Next.js 15 introduced support for async props, allowing the params prop
to be a Promise in Server Components. Updating the documentation ensures
that users follow the latest recommended practices and avoid confusion
when working with dynamic routes in Next.js 15.
How?
- Changed the Page component example to accept params as a Promise and
use await params to destructure the id.
- Updated the type annotation accordingly.
Abhishek Ghimire