Unverified Commit 6df3f236 authored by Joseph's avatar Joseph Committed by GitHub

docs(caching): clarify generateStaticParams prebuild and recommend max for CMS (#95081)

The caching guide and ISR without CC, did not reference, nor mention,
generateStaticParams.

Additionally, we have learned that agents do use `max` for CMS content
and such, but not as often as we'd like. The default cache life time,
has a revalidate of 15 minutes, which for content that changes rarely,
is too often. Note that `max` is defined as the life time for that case.

We could do a further expansion that, the 30 days is enough because
managed hosting likely evicts the generated asset after 30 days anyway,
and that maybe self-host can use longer revalidate too, and that way
have a discoverability path for defining a custom profile.
parent 1b1cf7b4
...@@ -192,6 +192,6 @@ See the [`revalidatePath` API reference](/docs/app/api-reference/functions/reval ...@@ -192,6 +192,6 @@ See the [`revalidatePath` API reference](/docs/app/api-reference/functions/reval
Cache data that doesn't depend on [runtime data](/docs/app/getting-started/caching#working-with-runtime-apis) and that you're OK serving from cache for a period of time. Use `use cache` with `cacheLife` to describe that behavior. Cache data that doesn't depend on [runtime data](/docs/app/getting-started/caching#working-with-runtime-apis) and that you're OK serving from cache for a period of time. Use `use cache` with `cacheLife` to describe that behavior.
For content management systems with update mechanisms, use tags with longer cache durations and rely on `revalidateTag` to refresh content when it actually changes, rather than expiring the cache preemptively. When content doesn't need time-based revalidation, for example data from a CMS, use [`cacheTag`](#cachetag) and a long [`cacheLife`](#cachelife) like `max` to keep it in the static shell. Configure the content source to trigger a webhook, or other notification, that calls [`revalidateTag`](#revalidatetag) when the content changes. This reduces unnecessary time-based revalidation for content that hasn't changed.
> **Good to know:** In serverless environments, in-memory cache entries may not persist across revalidations. See [runtime caching considerations](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations) for details. > **Good to know:** In serverless environments, in-memory cache entries may not persist across revalidations. See [runtime caching considerations](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations) for details.
...@@ -362,3 +362,7 @@ async function Item({ id }) { ...@@ -362,3 +362,7 @@ async function Item({ id }) {
// ... // ...
} }
``` ```
## Statically generating dynamic routes
To prerender dynamic routes with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) and revalidate them over time, see the [Incremental Static Regeneration](/docs/app/guides/incremental-static-regeneration) guide.
...@@ -94,12 +94,13 @@ export default async function Page({ params }) { ...@@ -94,12 +94,13 @@ export default async function Page({ params }) {
Here's how this example works: Here's how this example works:
1. During `next build`, all known blog posts are generated 1. [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) enables ISR for the dynamic route by returning the list of posts to prerender
2. All requests made to these pages (e.g. `/blog/1`) are cached and instantaneous 2. During `next build`, a page is prerendered for each post
3. After 60 seconds has passed, the next request will still return the cached (now stale) page 3. All requests made to these pages (e.g. `/blog/1`) are cached and instantaneous
4. The cache is invalidated and a new version of the page begins generating in the background 4. After 60 seconds has passed, the next request will still return the cached (now stale) page
5. Once generated successfully, the next request will return the updated page and cache it for subsequent requests 5. The cache is invalidated and a new version of the page begins generating in the background
6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [dynamicParams](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) value. However, if the post does not exist, then 404 is returned. 6. Once generated successfully, the next request will return the updated page and cache it for subsequent requests
7. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [dynamicParams](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) value. However, if the post does not exist, then 404 is returned.
</AppOnly> </AppOnly>
...@@ -213,6 +214,7 @@ Here's how this example works: ...@@ -213,6 +214,7 @@ Here's how this example works:
### Functions ### Functions
- [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params)
- [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) - [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath)
- [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) - [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag)
......
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