next 16.2.8 → 16.2.10

package/dist/docs/01-app/02-guides/draft-mode.md

@@ -1,7 +1,7 @@
 ---
 title: How to preview content with Draft Mode in Next.js
 nav_title: Draft Mode
-description: Next.js has draft mode to toggle between static and dynamic pages. You can learn how it works with App Router here.
+description: Bypass Next.js caching for a request so editors can preview unpublished content from a headless CMS.
 related:
   title: Next Steps
   description: See the API reference for more information on how to use Draft Mode.
@@ -9,27 +9,46 @@ related:
     - app/api-reference/functions/draft-mode
 ---
 
-**Draft Mode** allows you to preview draft content from your headless CMS in your Next.js application. This is useful for static pages that are generated at build time as it allows you to switch to [dynamic rendering](/docs/app/glossary#dynamic-rendering) and see the draft changes without having to rebuild your entire site.
+**Draft Mode** lets editors see how draft or in-progress content will render on your site, without waiting for revalidation. While an editor is in Draft Mode, cached or pre-rendered content is bypassed, and fetched from upstream sources directly. Other visitors continue to see the cached or pre-rendered version of the page.
 
-This page walks through how to enable and use Draft Mode.
+Your data-fetching code does not need to change if your CMS serves draft and published content from the same URL. Otherwise, see [When your CMS uses a separate draft endpoint](#when-your-cms-uses-a-separate-draft-endpoint).
 
-## Step 1: Create a Route Handler
+## What Draft Mode does
 
-Create a [Route Handler](/docs/app/api-reference/file-conventions/route). It can have any name, for example, `app/api/draft/route.ts`.
+When Draft Mode is enabled for a request:
 
-```ts filename="app/api/draft/route.ts" switcher
-export async function GET(request: Request) {
-  return new Response('')
-}
-```
+- `fetch()` calls skip the Next.js fetch cache and hit the network directly.
+- Components and functions inside [`'use cache'`](/docs/app/api-reference/directives/use-cache) re-execute on every request, and their results are not saved to the cache.
+- [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache) reads and writes are bypassed in the same way.
+- The page is excluded from the ISR response cache and is served with `Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate`.
 
-```js filename="app/api/draft/route.js" switcher
-export async function GET() {
-  return new Response('')
-}
-```
+The effect applies whether the page is statically generated, served from cache, or revalidated through ISR.
+
+## What this guide covers
+
+This guide assumes:
+
+- Your headless CMS supports configurable preview URLs (most do).
+- The CMS opens a URL like `/api/draft?secret=XXX&slug=/posts/foo` in a new tab when an editor clicks "Preview". The secret is a shared token; the slug is the path to preview.
+- Your Next.js app validates the secret, enables Draft Mode, and redirects to the slug.
 
-Then, import the [`draftMode`](/docs/app/api-reference/functions/draft-mode) function and call the `enable()` method.
+With that contract in mind, the rest of this guide walks through:
+
+1. Creating a Route Handler that enables Draft Mode by setting a cookie.
+2. Securing that handler with the shared secret and slug from the CMS.
+3. Rendering pages that read the latest draft.
+4. Showing a preview banner with an exit form.
+
+Then, depending on your setup:
+
+- [Draft Mode with Cache Components](#draft-mode-with-cache-components) for surfacing the preview state from a `'use cache'` boundary.
+- [When your CMS uses a separate draft endpoint](#when-your-cms-uses-a-separate-draft-endpoint) for branching the fetch URL on `isEnabled`.
+
+> **Good to know:** `GET` is meant to be a safe, read-only method. Operations that affect future requests, like enabling Draft Mode via a cookie, should use `POST`. The entry handler uses `GET` because we're assuming a CMS preview integration: the CMS opens the URL in a new browser tab, which is a `GET` request. The exit flow in Step 4 uses `POST` (via [Server Action](/docs/app/getting-started/mutating-data) or `POST` Route Handler).
+
+## Step 1: Create a Route Handler
+
+Create a [Route Handler](/docs/app/api-reference/file-conventions/route) that sets the Draft Mode cookie. It can have any name, for example, `app/api/draft/route.ts`.
 
 ```ts filename="app/api/draft/route.ts" switcher
 import { draftMode } from 'next/headers'
@@ -51,17 +70,19 @@ export async function GET(request) {
 }
 ```
 
-This will set a **cookie** to enable draft mode. Subsequent requests containing this cookie will trigger draft mode and change the behavior of statically generated pages.
+`draft.enable()` sets a cookie named `__prerender_bypass`. Subsequent requests that carry this cookie skip every cache layer listed above.
+
+You can test this manually by visiting `/api/draft` and looking at your browser's developer tools. Notice the `Set-Cookie` response header.
 
-You can test this manually by visiting `/api/draft` and looking at your browser’s developer tools. Notice the `Set-Cookie` response header with a cookie named `__prerender_bypass`.
+As written, the handler is public: anyone who hits `/api/draft` enables Draft Mode for themselves. Step 2 closes that with a shared secret so only your CMS can call it.
 
-## Step 2: Access the Route Handler from your Headless CMS
+## Step 2: Access the Route Handler from your headless CMS
 
-> These steps assume that the headless CMS you’re using supports setting **custom draft URLs**. If it doesn’t, you can still use this method to secure your draft URLs, but you’ll need to construct and access the draft URL manually. The specific steps will vary depending on which headless CMS you’re using.
+> These steps assume that the headless CMS you're using supports setting **custom draft URLs**. If it doesn't, you can still use this method to secure your draft URLs, but you'll need to construct and access the draft URL manually. The specific steps will vary depending on which headless CMS you're using.
 
 To securely access the Route Handler from your headless CMS:
 
-1. Create a **secret token string** using a token generator of your choice. This secret will only be known by your Next.js app and your headless CMS.
+1. Create a **secret token string** using a token generator of your choice. This secret is only known to your Next.js app and your headless CMS.
 2. If your headless CMS supports setting custom draft URLs, specify a draft URL (this assumes that your Route Handler is located at `app/api/draft/route.ts`). For example:
 
 ```bash filename="Terminal"
@@ -72,41 +93,35 @@ https://<your-site>/api/draft?secret=<token>&slug=<path>
 > - `<token>` should be replaced with the secret token you generated.
 > - `<path>` should be the path for the page that you want to view. If you want to view `/posts/one`, then you should use `&slug=/posts/one`.
 >
-> Your headless CMS might allow you to include a variable in the draft URL so that `<path>` can be set dynamically based on the CMS’s data like so: `&slug=/posts/{entry.fields.slug}`
+> Your headless CMS might allow you to include a variable in the draft URL so that `<path>` can be set dynamically based on the CMS's data like so: `&slug=/posts/{entry.fields.slug}`
 
-3. In your Route Handler, check that the secret matches and that the `slug` parameter exists (if not, the request should fail), call `draftMode.enable()` to set the cookie. Then, redirect the browser to the path specified by `slug`:
+3. In your Route Handler, check that the secret matches and that the `slug` parameter exists (if not, the request should fail), call `draft.enable()` to set the cookie, then redirect the browser to the path specified by `slug`:
 
 ```ts filename="app/api/draft/route.ts" switcher
 import { draftMode } from 'next/headers'
 import { redirect } from 'next/navigation'
 
 export async function GET(request: Request) {
-  // Parse query string parameters
   const { searchParams } = new URL(request.url)
   const secret = searchParams.get('secret')
   const slug = searchParams.get('slug')
 
-  // Check the secret and next parameters
   // This secret should only be known to this Route Handler and the CMS
   if (secret !== 'MY_SECRET_TOKEN' || !slug) {
     return new Response('Invalid token', { status: 401 })
   }
 
-  // Fetch the headless CMS to check if the provided `slug` exists
-  // getPostBySlug would implement the required fetching logic to the headless CMS
+  // Verify the slug exists in the CMS before enabling Draft Mode
   const post = await getPostBySlug(slug)
-
-  // If the slug doesn't exist prevent draft mode from being enabled
   if (!post) {
     return new Response('Invalid slug', { status: 401 })
   }
 
-  // Enable Draft Mode by setting the cookie
   const draft = await draftMode()
   draft.enable()
 
-  // Redirect to the path from the fetched post
-  // We don't redirect to searchParams.slug as that might lead to open redirect vulnerabilities
+  // Redirect to the path from the fetched post, not from searchParams,
+  // to avoid open redirect vulnerabilities
   redirect(post.slug)
 }
 ```
@@ -116,132 +131,152 @@ import { draftMode } from 'next/headers'
 import { redirect } from 'next/navigation'
 
 export async function GET(request) {
-  // Parse query string parameters
   const { searchParams } = new URL(request.url)
   const secret = searchParams.get('secret')
   const slug = searchParams.get('slug')
 
-  // Check the secret and next parameters
-  // This secret should only be known to this Route Handler and the CMS
   if (secret !== 'MY_SECRET_TOKEN' || !slug) {
     return new Response('Invalid token', { status: 401 })
   }
 
-  // Fetch the headless CMS to check if the provided `slug` exists
-  // getPostBySlug would implement the required fetching logic to the headless CMS
   const post = await getPostBySlug(slug)
-
-  // If the slug doesn't exist prevent draft mode from being enabled
   if (!post) {
     return new Response('Invalid slug', { status: 401 })
   }
 
-  // Enable Draft Mode by setting the cookie
   const draft = await draftMode()
   draft.enable()
 
-  // Redirect to the path from the fetched post
-  // We don't redirect to searchParams.slug as that might lead to open redirect vulnerabilities
   redirect(post.slug)
 }
 ```
 
-If it succeeds, then the browser will be redirected to the path you want to view with the draft mode cookie.
-
-## Step 3: Preview the Draft Content
-
-The next step is to update your page to check the value of `draftMode().isEnabled`.
+If it succeeds, the browser is redirected to the target path with the Draft Mode cookie set.
 
-If you request a page which has the cookie set, then data will be fetched at **request time** (instead of at build time).
+## Step 3: Preview the draft content
 
-Furthermore, the value of `isEnabled` will be `true`.
+Because Draft Mode bypasses the cache automatically, your page does not need to know whether Draft Mode is on to receive fresh content. Fetch as you normally would:
 
-```tsx filename="app/page.tsx" switcher
-// page that fetches data
-import { draftMode } from 'next/headers'
-
-async function getData() {
-  const { isEnabled } = await draftMode()
+```tsx filename="app/posts/[slug]/page.tsx" switcher
+async function getPost(slug: string) {
+  const res = await fetch(`https://cms.example.com/posts/${slug}`)
+  return res.json()
+}
 
-  const url = isEnabled
-    ? 'https://draft.example.com'
-    : 'https://production.example.com'
+export default async function Page({ params }: PageProps<'/posts/[slug]'>) {
+  const { slug } = await params
+  const post = await getPost(slug)
 
-  const res = await fetch(url)
+  return (
+    <main>
+      <h1>{post.title}</h1>
+      <article>{post.content}</article>
+    </main>
+  )
+}
+```
 
+```jsx filename="app/posts/[slug]/page.js" switcher
+async function getPost(slug) {
+  const res = await fetch(`https://cms.example.com/posts/${slug}`)
   return res.json()
 }
 
-export default async function Page() {
-  const { title, desc } = await getData()
+export default async function Page({ params }) {
+  const { slug } = await params
+  const post = await getPost(slug)
 
   return (
     <main>
-      <h1>{title}</h1>
-      <p>{desc}</p>
+      <h1>{post.title}</h1>
+      <article>{post.content}</article>
     </main>
   )
 }
 ```
 
-```jsx filename="app/page.js" switcher
-// page that fetches data
-import { draftMode } from 'next/headers'
+When the Draft Mode cookie is present, the `fetch` above skips the Next.js fetch cache and hits your CMS for the current draft. When it is not, the same request can be served from cache as usual.
 
-async function getData() {
-  const { isEnabled } = await draftMode()
+If your CMS uses a different URL for drafts rather than serving them from the same endpoint, see [When your CMS uses a separate draft endpoint](#when-your-cms-uses-a-separate-draft-endpoint).
 
-  const url = isEnabled
-    ? 'https://draft.example.com'
-    : 'https://production.example.com'
+## Step 4: Show a preview indicator
 
-  const res = await fetch(url)
+`isEnabled` is most useful as a signal to the editor: a banner that confirms they are looking at draft content, plus a way to exit. Render an indicator from your root layout so it appears on every preview page.
 
-  return res.json()
+```tsx filename="app/preview-banner.tsx" switcher
+import { draftMode } from 'next/headers'
+import { redirect } from 'next/navigation'
+
+async function exitPreview() {
+  'use server'
+  const draft = await draftMode()
+  draft.disable()
+  redirect('/')
 }
 
-export default async function Page() {
-  const { title, desc } = await getData()
+export async function PreviewBanner() {
+  const { isEnabled } = await draftMode()
+  if (!isEnabled) return null
 
   return (
-    <main>
-      <h1>{title}</h1>
-      <p>{desc}</p>
-    </main>
+    <aside role="status">
+      Preview mode is on.{' '}
+      <form action={exitPreview}>
+        <button type="submit">Exit preview</button>
+      </form>
+    </aside>
   )
 }
 ```
 
-If you access the draft Route Handler (with `secret` and `slug`) from your headless CMS or manually using the URL, you should now be able to see the draft content. And, if you update your draft without publishing, you should be able to view the draft.
+```jsx filename="app/preview-banner.js" switcher
+import { draftMode } from 'next/headers'
+import { redirect } from 'next/navigation'
 
-## Draft Mode with Cache Components
+async function exitPreview() {
+  'use server'
+  const draft = await draftMode()
+  draft.disable()
+  redirect('/')
+}
 
-When using [caching directives](/docs/app/api-reference/directives/use-cache), Draft Mode forces all cached functions and components to produce fresh results on every request. You do not need to add any special handling to your caching code.
+export async function PreviewBanner() {
+  const { isEnabled } = await draftMode()
+  if (!isEnabled) return null
 
-When Draft Mode is enabled:
+  return (
+    <aside role="status">
+      Preview mode is on.{' '}
+      <form action={exitPreview}>
+        <button type="submit">Exit preview</button>
+      </form>
+    </aside>
+  )
+}
+```
+
+Exiting Draft Mode also works with a `GET` Route Handler, but a `POST` is semantically more correct, for example via a form submitted through a [Server Action](/docs/app/getting-started/mutating-data) or to a `POST` Route Handler.
 
-- All functions and components under a caching directive scope re-execute on every request instead of serving from cache.
-- Results are not saved to the cache, so draft requests do not pollute cached content.
-- `fetch()` calls inside cached scopes use the original `fetch` implementation directly, without the Next.js fetch cache.
-- Response headers are set to `private, no-cache, no-store, max-age=0, must-revalidate`.
+If you do use a `GET` Route Handler, trigger it from a `<form method="GET">` rather than a [`<Link>`](/docs/app/api-reference/components/link). Next.js prefetches `<Link>` components by default, which would clear the cookie before the editor clicks. Forms are not prefetched, regardless of method.
 
-You can read if Draft Mode is enabled inside a caching directive scope, so you can conditionally fetch draft or published content:
+## Draft Mode with Cache Components
+
+You can read `isEnabled` inside a [`'use cache'`](/docs/app/api-reference/directives/use-cache) scope to render a preview indicator from a cached component. The cache bypass still applies, so the component re-executes with fresh data on every draft request.
 
-```tsx filename="app/post/[slug]/page.tsx" switcher
+```tsx filename="app/posts/[slug]/page.tsx" switcher
 import { draftMode } from 'next/headers'
 
 async function Post({ slug }: { slug: string }) {
   'use cache'
 
+  const post = await fetch(`https://cms.example.com/posts/${slug}`).then((r) =>
+    r.json()
+  )
   const { isEnabled } = await draftMode()
 
-  // Fetch draft or published content based on draft mode status
-  const post = isEnabled
-    ? await fetchDraftPost(slug)
-    : await fetchPublishedPost(slug)
-
   return (
     <article>
+      {isEnabled && <p role="status">Draft preview</p>}
       <h1>{post.title}</h1>
       <div>{post.content}</div>
     </article>
@@ -249,21 +284,20 @@ async function Post({ slug }: { slug: string }) {
 }
 ```
 
-```jsx filename="app/post/[slug]/page.js" switcher
+```jsx filename="app/posts/[slug]/page.js" switcher
 import { draftMode } from 'next/headers'
 
 async function Post({ slug }) {
   'use cache'
 
+  const post = await fetch(`https://cms.example.com/posts/${slug}`).then((r) =>
+    r.json()
+  )
   const { isEnabled } = await draftMode()
 
-  // Fetch draft or published content based on draft mode status
-  const post = isEnabled
-    ? await fetchDraftPost(slug)
-    : await fetchPublishedPost(slug)
-
   return (
     <article>
+      {isEnabled && <p role="status">Draft preview</p>}
       <h1>{post.title}</h1>
       <div>{post.content}</div>
     </article>
@@ -271,9 +305,38 @@ async function Post({ slug }) {
 }
 ```
 
-> **Good to know:**
->
-> - You can await the `draftMode()` promise inside a caching directive scope to read `isEnabled`, but other runtime APIs like `cookies()` and `headers()` are not allowed and will throw an error, even when Draft Mode is active. (The [`"use cache: private"`](/docs/app/api-reference/directives/use-cache-private) directive does allow access to `cookies()` and `headers()`.)
-> - You cannot call `draftMode().enable()` or `draftMode().disable()` inside a caching directive scope. Draft Mode can only be toggled in [Route Handlers](/docs/app/api-reference/file-conventions/route) or [Server Actions](/docs/app/getting-started/mutating-data).
+> **Good to know:** `draftMode().enable()` and `draftMode().disable()` cannot be called inside a caching directive scope; toggle Draft Mode from a [Route Handler](/docs/app/api-reference/file-conventions/route) or [Server Action](/docs/app/getting-started/mutating-data) instead.
+
+## When your CMS uses a separate draft endpoint
+
+If your CMS exposes draft content at a different URL or requires different credentials, branch your fetch on `isEnabled`:
+
+```tsx filename="app/posts/[slug]/page.tsx" switcher
+import { draftMode } from 'next/headers'
+
+async function getPost(slug: string) {
+  const { isEnabled } = await draftMode()
+  const baseUrl = isEnabled
+    ? 'https://cms.example.com/preview'
+    : 'https://cms.example.com/published'
+
+  const res = await fetch(`${baseUrl}/posts/${slug}`)
+  return res.json()
+}
+```
+
+```jsx filename="app/posts/[slug]/page.js" switcher
+import { draftMode } from 'next/headers'
+
+async function getPost(slug) {
+  const { isEnabled } = await draftMode()
+  const baseUrl = isEnabled
+    ? 'https://cms.example.com/preview'
+    : 'https://cms.example.com/published'
+
+  const res = await fetch(`${baseUrl}/posts/${slug}`)
+  return res.json()
+}
+```
 
-If your cached function needs values from `cookies()` or `headers()`, read them outside the caching directive scope and [pass them as arguments](/docs/app/getting-started/caching#passing-runtime-values-to-cached-functions).
+The cache bypass still applies to both branches; the fork only chooses where to read from.

package/dist/docs/01-app/02-guides/forms.md

@@ -4,7 +4,7 @@ nav_title: Forms
 description: Learn how to create forms in Next.js with React Server Actions.
 ---
 
-React Server Actions are [Server Functions](https://react.dev/reference/rsc/server-functions) that execute on the server. They can be called in Server and Client Components to handle form submissions. This guide will walk you through how to create forms in Next.js with Server Actions.
+React Server Actions are [Server Functions](https://react.dev/reference/rsc/server-functions) that execute on the server. They can be called in Server and Client Components to handle form submissions. This guide will walk you through how to create forms in Next.js with Server Actions. For Server Action behaviors beyond forms (single-roundtrip response, sequential dispatch, security, deployment), see [Server Actions and Mutations](/docs/app/guides/server-actions).
 
 > [!WARNING]
 > Always verify [authentication and authorization](/docs/app/guides/authentication) inside each Server Action, even if the form is only rendered on an authenticated page. See the [Data Security guide](/docs/app/guides/data-security) for more details.

package/dist/docs/01-app/02-guides/how-revalidation-works.md

@@ -50,7 +50,7 @@ Soft tags are automatically generated by Next.js based on the route path, prefix
 
 Soft tags enable [`revalidatePath()`](/docs/app/api-reference/functions/revalidatePath) to work through the same tag-based system. When `revalidatePath('/blog/hello')` is called, it invalidates cache entries associated with that path's leaf route tag and its ancestor layout soft tags (for example `_N_T_/layout`, `_N_T_/blog/layout`, `_N_T_/blog/hello/layout`, and `_N_T_/blog/hello`).
 
-In the [cache handler API](/docs/app/api-reference/config/next-config-js/cacheHandlers), soft tags are passed to the `get()` method as the `softTags` parameter. Your handler should check whether any soft tag has been invalidated after the cache entry's timestamp. The `getExpiration()` method returns the most recent revalidation timestamp across all provided tags, or `0` if none have been revalidated. Your handler should treat an entry as stale if the returned timestamp is newer than the entry's own timestamp. See the [cache handler API reference](/docs/app/api-reference/config/next-config-js/cacheHandlers#getexpiration) for the full semantics.
+In the [cache handler API](/docs/app/api-reference/config/next-config-js/cacheHandlers), soft tags are passed to the `get()` method as the `softTags` parameter. Your handler should check whether any soft tag has been invalidated after the cache entry's timestamp. The `getExpiration()` method returns the most recent revalidation timestamp across all provided tags, or `0` if none have been revalidated. It can also return `Infinity` to signal that the soft tags should instead be passed to `get()` and checked for expiration there. Your handler should treat an entry as stale if the returned timestamp is newer than the entry's own timestamp. See the [cache handler API reference](/docs/app/api-reference/config/next-config-js/cacheHandlers#getexpiration) for the full semantics.
 
 ## Multi-Instance Considerations
 
@@ -89,7 +89,7 @@ If a CDN caches Next.js responses, it should respect the `Vary` header and the `
 The revalidation system prioritizes availability over strict consistency. Content is always served, even when infrastructure guarantees cannot be fully met:
 
 - **Cache write failure**: the response is still served to the user because writes are asynchronous. The cache entry is lost, and the next request triggers a fresh render.
-- **Cache read failure**: your handler should catch internal errors and return `undefined` (the cache miss signal). The route is then server-rendered fresh. The framework does not wrap `get()` in a try/catch, so unhandled exceptions will propagate as render errors.
+- **Cache read failure**: your handler should catch internal errors and return `undefined` (the cache miss signal). The route is then server-rendered fresh. A thrown error is not treated as a cache miss; it propagates as a render error, so always return `undefined` to signal a miss.
 - **HTML/RSC cache inconsistency**: if a CDN caches HTML and RSC responses with different TTLs or invalidation timing, users may see mismatched content during client-side navigation. Cache them together and respect the `Vary` header to avoid this.
 - **Cross-deployment skew**: during rolling deployments, configure [`deploymentId`](/docs/app/api-reference/config/next-config-js/deploymentId) so that a build ID change triggers a hard navigation to fetch consistent content.
 

package/dist/docs/01-app/02-guides/mdx.md

@@ -810,6 +810,7 @@ module.exports = withMDX({
     mdxRs: {
       jsxRuntime?: string            // Custom jsx runtime
       jsxImportSource?: string       // Custom jsx import source,
+      providerImportSource?: string  // Module providing a `useMDXComponents` context
       mdxType?: 'gfm' | 'commonmark' // Configure what kind of mdx syntax will be used to parse & transform
     },
   },