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() { ...@@ -86,43 +86,62 @@ export async function GET() {
#### With Cache Components #### 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 **Static example** - doesn't access dynamic or runtime data, so it will be prerendered at build time:
import { cacheTag } from 'next/cache'
async function getPosts() { ```tsx filename="app/api/project-info/route.ts"
'use cache' export async function GET() {
cacheTag('posts') return Response.json({
projectName: 'Next.js',
const posts = await fetchPosts() })
return posts
} }
```
**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() { export async function GET() {
const posts = await getPosts() return Response.json({
return Response.json(posts) randomNumber: Math.random(),
})
} }
``` ```
```js filename="app/api/posts/route.js" switcher **Runtime data example** - accesses request-specific data. Prerendering terminates when runtime APIs like `headers()` are called:
import { cacheTag } from 'next/cache'
async function getPosts() { ```tsx filename="app/api/user-agent/route.ts"
'use cache' import { headers } from 'next/headers'
cacheTag('posts')
export async function GET() {
const headersList = await headers()
const userAgent = headersList.get('user-agent')
const posts = await fetchPosts() return Response.json({ userAgent })
return posts
} }
```
> **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() { export async function GET() {
const posts = await getPosts() const products = await getProducts()
return Response.json(posts) 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 ### 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