From 47f8dd1e432b3a8f4d52b674470dc12d009616fd Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Tue, 21 Oct 2025 14:42:58 +0200 Subject: [PATCH 1/2] docs: use cache feedback --- .../01-directives/use-cache.mdx | 29 +++++-- .../01-next-config-js/cacheComponents.mdx | 6 ++ .../incrementalCacheHandlerPath.mdx | 2 + .../05-config/01-next-config-js/ppr.mdx | 87 ------------------- 4 files changed, 31 insertions(+), 93 deletions(-) delete mode 100644 docs/01-app/03-api-reference/05-config/01-next-config-js/ppr.mdx diff --git a/docs/01-app/03-api-reference/01-directives/use-cache.mdx b/docs/01-app/03-api-reference/01-directives/use-cache.mdx index b0e920d2bff4d..1042b51de1feb 100644 --- a/docs/01-app/03-api-reference/01-directives/use-cache.mdx +++ b/docs/01-app/03-api-reference/01-directives/use-cache.mdx @@ -148,7 +148,7 @@ export default function Layout({ children }) { } ``` -Any components imported and nested in `page` file will inherit the cache behavior of `page`. +Any components imported and nested in `page` file are part of the cache output associated with the `page`. ```tsx filename="app/page.tsx" switcher 'use cache' @@ -243,23 +243,34 @@ export async function getData() { ### Interleaving -If you need to pass non-serializable arguments to a cacheable function, you can pass them as `children`. This means the `children` reference can change without affecting the cache entry. +In React, composition with `children` or slots is a well-known pattern for building flexible components. When using `use cache`, you can continue to compose your UI in this way. Anything included as `children`, or other compositional slots, in the returned JSX will be passed through the cached component without affecting its cache. + +As long as you don't directly reference any of the JSX slots inside the body of the cacheable function itself, their presence in the returned output won't affect the cache entry. ```tsx filename="app/page.tsx" switcher export default async function Page() { const uncachedData = await getData() return ( - + // Pass compositional slots as props, e.g. header and children + Home}> + {/* DynamicComponent is provided as the children slot */} ) } -async function CacheComponent({ children }: { children: ReactNode }) { +async function CacheComponent({ + header, // header: a compositional slot, injected as a prop + children, // children: another slot for nested composition +}: { + header: ReactNode + children: ReactNode +}) { 'use cache' const cachedData = await fetch('/api/cached-data') return (
+ {header} {children}
@@ -271,17 +282,23 @@ async function CacheComponent({ children }: { children: ReactNode }) { export default async function Page() { const uncachedData = await getData() return ( - + // Pass compositional slots as props, e.g. header and children + Home}> + {/* DynamicComponent is provided as the children slot */} ) } -async function CacheComponent({ children }) { +async function CacheComponent({ + header, // header: a compositional slot, injected as a prop + children, // children: another slot for nested composition +}) { 'use cache' const cachedData = await fetch('/api/cached-data') return (
+ {header} {children}
diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/cacheComponents.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/cacheComponents.mdx index c0adb18984402..164fa5452bc66 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/cacheComponents.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/cacheComponents.mdx @@ -32,3 +32,9 @@ When `cacheComponents` is enabled, you can use the following cache functions and ## Notes - While `cacheComponents` can optimize performance by ensuring fresh data fetching during runtime, it may also introduce additional latency compared to serving pre-rendered content. + +## Version History + +| Version | Change | +| ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| 16.0.0 | `cacheComponents` introduced. This flag controls the `ppr`, `useCache`, and `dynamicIO` flags as a single, unified configuration. | diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/incrementalCacheHandlerPath.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/incrementalCacheHandlerPath.mdx index f92731f7262d7..5fa4dd685c082 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/incrementalCacheHandlerPath.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/incrementalCacheHandlerPath.mdx @@ -6,6 +6,8 @@ description: Configure the Next.js cache used for storing and revalidating data You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js application. +> **Good to know**: The `cacheHandler` configuration is specifically used by Next.js for server cache operations such as storing and revalidating ISR and route handler responses. It is not used by `'use cache'`, `'use cache: remote'`, nor `'use cache: private'`, which manage their own cache independently. + ```js filename="next.config.js" module.exports = { cacheHandler: require.resolve('./cache-handler.js'), diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/ppr.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/ppr.mdx deleted file mode 100644 index 02ec900156f19..0000000000000 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/ppr.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: ppr -description: Learn how to enable Partial Prerendering in Next.js. -version: canary -related: - title: Learn more about Partial Prerendering - links: - - app/getting-started/partial-prerendering ---- - -Partial Prerendering (PPR) enables you to combine static and dynamic components together in the same route. Learn more about [PPR](/docs/app/getting-started/partial-prerendering). - -## Using Partial Prerendering - -### Incremental Adoption (Version 15) - -In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/api-reference/file-conventions/layout) and [pages](/docs/app/api-reference/file-conventions/page) by setting the [`ppr`](/docs/app/api-reference/config/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: - -```ts filename="next.config.ts" switcher -import type { NextConfig } from 'next' - -const nextConfig: NextConfig = { - experimental: { - ppr: 'incremental', - }, -} - -export default nextConfig -``` - -```js filename="next.config.js" switcher -/** @type {import('next').NextConfig} */ -const nextConfig = { - experimental: { - ppr: 'incremental', - }, -} - -module.exports = nextConfig -``` - -```tsx filename="app/page.tsx" switcher -import { Suspense } from "react" -import { StaticComponent, DynamicComponent, Fallback } from "@/app/ui" - -export const experimental_ppr = true - -export default function Page() { - return { - <> - - }> - - - - }; -} -``` - -```jsx filename="app/page.js" switcher -import { Suspense } from "react" -import { StaticComponent, DynamicComponent, Fallback } from "@/app/ui" - -export const experimental_ppr = true - -export default function Page() { - return { - <> - - }> - - - - }; -} -``` - -> **Good to know**: -> -> - 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. -> - `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. - -| Version | Changes | -| --------- | ------------------------------------------- | -| `v15.0.0` | experimental `incremental` value introduced | -| `v14.0.0` | experimental `ppr` introduced | From a5809c773076e7c8c528076df7ea61a49565cf20 Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Tue, 21 Oct 2025 14:45:00 +0200 Subject: [PATCH 2/2] docs: broken sentence + entry --- docs/01-app/03-api-reference/01-directives/use-cache.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-app/03-api-reference/01-directives/use-cache.mdx b/docs/01-app/03-api-reference/01-directives/use-cache.mdx index 1042b51de1feb..683ecafb807dd 100644 --- a/docs/01-app/03-api-reference/01-directives/use-cache.mdx +++ b/docs/01-app/03-api-reference/01-directives/use-cache.mdx @@ -243,7 +243,7 @@ export async function getData() { ### Interleaving -In React, composition with `children` or slots is a well-known pattern for building flexible components. When using `use cache`, you can continue to compose your UI in this way. Anything included as `children`, or other compositional slots, in the returned JSX will be passed through the cached component without affecting its cache. +In React, composition with `children` or slots is a well-known pattern for building flexible components. When using `use cache`, you can continue to compose your UI in this way. Anything included as `children`, or other compositional slots, in the returned JSX will be passed through the cached component without affecting its cache entry. As long as you don't directly reference any of the JSX slots inside the body of the cacheable function itself, their presence in the returned output won't affect the cache entry.