Unverified Commit fedee7d7 authored by Joseph's avatar Joseph Committed by GitHub

docs: follow up to getting started CC and use-cache API ref (#85582)

Expanding on the Getting started for CC and also extending `use cache`

---------
Co-authored-by: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
parent d174698c
......@@ -86,43 +86,62 @@ export async function GET() {
#### With Cache Components
When using [Cache Components](/docs/app/getting-started/cache-components), you can use the [`use cache`](/docs/app/api-reference/directives/use-cache) directive to cache data fetching within your Route Handlers. Route Handlers are dynamic by default, but can be pre-rendered at build time if they don't use runtime or dynamic data.
When [Cache Components](/docs/app/getting-started/cache-components) is enabled, `GET` Route Handlers follow the same model as normal UI routes in your application. They run at request time by default, can be prerendered when they don't access dynamic or runtime data, and you can use `use cache` to include dynamic data in the static response.
```ts filename="app/api/posts/route.ts" switcher
import { cacheTag } from 'next/cache'
**Static example** - doesn't access dynamic or runtime data, so it will be prerendered at build time:
async function getPosts() {
'use cache'
cacheTag('posts')
const posts = await fetchPosts()
return posts
```tsx filename="app/api/project-info/route.ts"
export async function GET() {
return Response.json({
projectName: 'Next.js',
})
}
```
**Dynamic example** - accesses non-deterministic operations. During the build, prerendering stops when `Math.random()` is called, deferring to request-time rendering:
```tsx filename="app/api/random-number/route.ts"
export async function GET() {
const posts = await getPosts()
return Response.json(posts)
return Response.json({
randomNumber: Math.random(),
})
}
```
```js filename="app/api/posts/route.js" switcher
import { cacheTag } from 'next/cache'
**Runtime data example** - accesses request-specific data. Prerendering terminates when runtime APIs like `headers()` are called:
async function getPosts() {
'use cache'
cacheTag('posts')
```tsx filename="app/api/user-agent/route.ts"
import { headers } from 'next/headers'
export async function GET() {
const headersList = await headers()
const userAgent = headersList.get('user-agent')
const posts = await fetchPosts()
return posts
return Response.json({ userAgent })
}
```
> **Good to know**: Prerendering stops if the `GET` handler accesses network requests, database queries, async file system operations, request object properties (like `req.url`, `request.headers`, `request.cookies`, `request.body`), runtime APIs like [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), [`connection()`](/docs/app/api-reference/functions/connection), or non-deterministic operations.
**Cached example** - accesses dynamic data (database query) but caches it with `use cache`, allowing it to be included in the prerendered response:
```tsx filename="app/api/products/route.ts"
import { cacheLife } from 'next/cache'
export async function GET() {
const posts = await getPosts()
return Response.json(posts)
const products = await getProducts()
return Response.json(products)
}
async function getProducts() {
'use cache'
cacheLife('hours')
return await db.query('SELECT * FROM products')
}
```
See the [Cache Components documentation](/docs/app/getting-started/cache-components#route-handlers-with-cache-components) for more details on caching strategies and revalidation.
> **Good to know**: `use cache` cannot be used directly inside a Route Handler body; extract it to a helper function. Cached responses revalidate according to `cacheLife` when a new request arrives.
### Special Route Handlers
......
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