Unverified Commit 726dabf0 authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

docs: Improve PPR config/rendering sections (#68210)

Co-authored-by: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
parent c470e1c0
--- ---
title: Partial Prerendering (experimental) title: Partial Prerendering
description: Learn how to combine the benefits of static and dynamic rendering with Partial Prerendering. description: Learn how to combine the benefits of static and dynamic rendering with Partial Prerendering.
--- ---
> Partial Prerendering is an **experimental** feature and subject to change. Partial Prerendering (PPR) enables you to combine static and dynamic components together in the same route.
Partial Prerendering (PPR) is a rendering strategy that combines the benefits of static and dynamic rendering on the same route. With PPR, you can wrap any [dynamic](/docs/app/building-your-application/rendering/server-components#dynamic-rendering) components in a [Suspense](https://react.dev/reference/react/Suspense) boundary. When a new request comes in, Next.js will immediately serve a static HTML shell from the cache, then render and [stream](/docs/app/building-your-application/rendering/server-components#streaming) the dynamic parts in the same HTTP request. During the build, Next.js prerenders as much of the route as possible. If [dynamic](/docs/app/building-your-application/rendering/server-components#dynamic-rendering) code is detected, like reading from the incoming request, you can wrap the relevant component with a [React Suspense](https://react.dev/reference/react/Suspense) boundary. The Suspense boundary fallback will then be included in the prerendered HTML.
> **Note:** Partial Prerendering is an **experimental** feature and subject to change. It is not ready for production use.
<Image <Image
alt="Partially Prerendered Product Page showing static nav and product information, and dynamic cart and recommended products" alt="Partially Prerendered Product Page showing static nav and product information, and dynamic cart and recommended products"
...@@ -17,18 +19,30 @@ Partial Prerendering (PPR) is a rendering strategy that combines the benefits of ...@@ -17,18 +19,30 @@ Partial Prerendering (PPR) is a rendering strategy that combines the benefits of
> **🎥 Watch:** Why PPR and how it works → [YouTube (10 minutes)](https://www.youtube.com/watch?v=MTcPrTIBkpA). > **🎥 Watch:** Why PPR and how it works → [YouTube (10 minutes)](https://www.youtube.com/watch?v=MTcPrTIBkpA).
## Incremental Adoption (Version 15) ## Background
PPR enables your Next.js server to immediately send prerendered content.
To prevent client to server waterfalls, dynamic components begin streaming from the server in parallel while serving the initial prerender. This ensures dynamic components can begin rendering before client JavaScript has been loaded in the browser.
To prevent creating many HTTP requests for each dynamic component, PPR is able to combine the static prerender and dynamic components together into a single HTTP request. This ensures there are not multiple network roundtrips needed for each dynamic component.
## Using Partial Prerendering
### Incremental Adoption (Version 15)
In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file: In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
```js filename="next.config.js" ```js filename="next.config.ts"
const nextConfig = { import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: { experimental: {
ppr: 'incremental', ppr: 'incremental'
}, }
} }
module.exports = nextConfig export default nextConfig
``` ```
```tsx filename="app/page.tsx" switcher ```tsx filename="app/page.tsx" switcher
...@@ -73,7 +87,7 @@ export default function Page() { ...@@ -73,7 +87,7 @@ export default function Page() {
> - `experimental_ppr` will apply to all children of the route segment, including nested layouts and pages. You don't have to add it to every file, only the top segment of a route. > - `experimental_ppr` will apply to all children of the route segment, including nested layouts and pages. You don't have to add it to every file, only the top segment of a route.
> - To disable PPR for children segments, you can set `experimental_ppr` to `false` in the child segment. > - To disable PPR for children segments, you can set `experimental_ppr` to `false` in the child segment.
## Enabling PPR (Version 14) ### Enabling PPR (Version 14)
For version 14, you can enable it by adding the [`ppr`](/docs/app/api-reference/next-config-js/ppr) option to your `next.config.js` file. This will apply to all routes in your application: For version 14, you can enable it by adding the [`ppr`](/docs/app/api-reference/next-config-js/ppr) option to your `next.config.js` file. This will apply to all routes in your application:
...@@ -86,3 +100,117 @@ const nextConfig = { ...@@ -86,3 +100,117 @@ const nextConfig = {
module.exports = nextConfig module.exports = nextConfig
``` ```
## Dynamic Components
When creating the prender for your route during `next build`, Next.js requires that dynamic functions are wrapped with React Suspense. The `fallback` is then included in the prerender.
For example, using functions like `cookies()` or `headers()`:
```jsx filename="app/user.js" switcher
import { cookies } from 'next/headers'
export function User() {
const session = cookies().get('session')?.value
return '...'
}
```
```tsx filename="app/user.tsx" switcher
import { cookies } from 'next/headers'
export function User() {
const session = cookies().get('session')?.value
return '...'
}
```
This component requires looking at the incoming request to read cookies. To use this with PPR, you should wrap the component with Suspense:
```tsx filename="app/page.tsx" switcher
import { Suspense } from 'react'
import { User, AvatarSkeleton } from './user'
export const experimental_ppr = true
export default function Page() {
return (
<section>
<h1>This will be prerendered</h1>
<Suspense fallback={<AvatarSkeleton />}>
<User />
</Suspense>
</section>
)
}
```
```jsx filename="app/page.js" switcher
import { Suspense } from 'react'
import { User, AvatarSkeleton } from './user'
export const experimental_ppr = true
export default function Page() {
return (
<section>
<h1>This will be prerendered</h1>
<Suspense fallback={<AvatarSkeleton />}>
<User />
</Suspense>
</section>
)
}
```
Components only opt into dynamic rendering when the value is accessed.
For example, if you are reading `searchParams` from a `page`, you can forward this value to another component as a prop:
```tsx filename="app/page.tsx" switcher
import { Table } from './table'
export default function Page({
searchParams,
}: {
searchParams: { sort: string }
}) {
return (
<section>
<h1>This will be prerendered</h1>
<Table searchParams={searchParams} />
</section>
)
}
```
```jsx filename="app/page.js" switcher
import { Table } from './table'
export default function Page({ searchParams }) {
return (
<section>
<h1>This will be prerendered</h1>
<Table searchParams={searchParams} />
</section>
)
}
```
Inside of the table component, accessing the value from `searchParams` will make the component run dynamically:
```tsx filename="app/table.tsx" switcher
export function Table({ searchParams }: { searchParams: { sort: string } }) {
const sort = searchParams.sort === 'true'
return '...'
}
```
```jsx filename="app/table.js" switcher
export function Table({ searchParams }: {
searchParams: { sort: string }
}) {
const sort = searchParams.sort === 'true';
return '...'
}
```
...@@ -244,6 +244,16 @@ module.exports = { ...@@ -244,6 +244,16 @@ module.exports = {
} }
``` ```
### Partial Prerendering
[Partial Prendering (experimental)](/docs/app/building-your-application/rendering/partial-prerendering) works by default with Next.js and is not a CDN feature. This includes deployment as a Node.js server (through `next start`) and when used with a Docker container.
### Usage with CDNs
When using a CDN in front on your Next.js application, the page will include `Cache-Control: private` response header when dynamic APIs are accessed. This ensures that the resulting HTML page is marked as non-cachable. If the page is fully prerendered to static, it will include `Cache-Control: public` to allow the page to be cached on the CDN.
If you don't need a mix of both static and dynamic components, you can make your entire route static and cache the output HTML on a CDN. This Automatic Static Optimization is the default behavior when running `next build` if dynamic APIs are not used.
</AppOnly> </AppOnly>
<PagesOnly> <PagesOnly>
......
--- ---
title: Partial Prerendering (experimental) title: Partial Prerendering
nav_title: ppr (experimental) nav_title: ppr (experimental)
description: Learn how to enable Partial Prerendering (experimental) in Next.js 14. description: Learn how to enable Partial Prerendering (experimental) in Next.js.
related:
title: Learn more about Partial Prerendering
links:
- app/building-your-application/rendering/partial-prerendering
--- ---
> Partial Prerendering is an **experimental** feature and subject to change. Partial Prerendering (PPR) enables you to combine static and dynamic components together in the same route. Learn more about [PPR](/docs/app/building-your-application/rendering/partial-prerendering).
Partial Prerendering is an experimental feature that allows static portions of a route to be prerendered and served from the cache with dynamic holes streamed in, all in a single HTTP request. > **Note:** Partial Prerendering is an **experimental** feature and subject to change. It is not ready for production use.
Incremental support is available in Next.js 15, allowing you to opt-in to Partial Prerendering for specific routes and layouts. ## Using Partial Prerendering
To enable Partial Prerendering, set the experimental `ppr` flag to `incremental`: ### Incremental Adoption (Version 15)
```js filename="next.config.js" In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
/** @type {import('next').NextConfig} */
const nextConfig = { ```js filename="next.config.ts"
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: { experimental: {
ppr: 'incremental', ppr: 'incremental'
}, }
} }
module.exports = nextConfig export default nextConfig
``` ```
## Options ```tsx filename="app/page.tsx" switcher
import { Suspense } from "react"
import { StaticComponent, DynamicComponent, Fallback } from "@/app/ui"
- `incremental`: Allows you to incrementally opt-in layouts and pages, and should be used with the [`experimental_ppr`](/docs/app/api-reference/file-conventions/route-segment-config#experimental_ppr) route config option. export const experimental_ppr = true
- `true`: Enables Partial Prerendering for all routes in your application.
We recommend using `incremental` first. Once all the routes in your application have PPR enabled, it’ll be considered safe for you to set the `ppr` value to `true`, and enable it for the entire app and all future routes. export default function Page() {
return {
<>
<StaticComponent />
<Suspense fallback={<Fallback />}>
<DynamicComponent />
</Suspense>
</>
};
}
```
```jsx filename="app/page.js" switcher
import { Suspense } from "react"
import { StaticComponent, DynamicComponent, Fallback } from "@/app/ui"
> **Good to know:** export const experimental_ppr = true
export default function Page() {
return {
<>
<StaticComponent />
<Suspense fallback={<Fallback />}>
<DynamicComponent />
</Suspense>
</>
};
}
```
> **Good to know**:
> >
> - When using `incremental`, routes that don't have `experimental_ppr` will default to `false` and will not be prerendered using Partial Prerendering. You need to explicitly opt-in to Partial Prerendering for each route. > - Routes that don't have `experimental_ppr` will default to `false` and will not be prerendered using PPR. You need to explicitly opt-in to PPR for each route.
> - Partial Prerendering does not yet apply to client-side navigations. We are actively working on this. > - `experimental_ppr` will apply to all children of the route segment, including nested layouts and pages. You don't have to add it to every file, only the top segment of a route.
> - Partial Prerendering is designed for the [Node.js runtime](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) only. Using the Edge Runtime is not needed when you can instantly serve the static shell. > - To disable PPR for children segments, you can set `experimental_ppr` to `false` in the child segment.
### Enabling PPR (Version 14)
For version 14, you can enable it by adding the [`ppr`](/docs/app/api-reference/next-config-js/ppr) option to your `next.config.js` file. This will apply to all routes in your application:
Learn more about Partial Prerendering in the [Next.js Learn course](/learn/dashboard-app/partial-prerendering). ```js filename="next.config.js"
const nextConfig = {
experimental: {
ppr: true,
},
}
module.exports = nextConfig
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment