Unverified Commit a549889b authored by Zack Tanner's avatar Zack Tanner Committed by GitHub

docs lint fixes (#71813)

Follow-ups to #71812
parent 9499cc16
...@@ -18,15 +18,15 @@ The `use cache` directive designates a component, function, or file to be cached ...@@ -18,15 +18,15 @@ The `use cache` directive designates a component, function, or file to be cached
Enable support for the `use cache` directive with the `dynamicIO` flag in your `next.config.ts` file: Enable support for the `use cache` directive with the `dynamicIO` flag in your `next.config.ts` file:
```ts filename="next.config.ts" ```ts filename="next.config.ts"
import type { NextConfig } from 'next'; import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
experimental: { experimental: {
dynamicIO: true, dynamicIO: true,
} },
}; }
export default nextConfig; export default nextConfig
``` ```
> The `use cache` directive will be available separately from the`dynamicIO` flag in the future. > The `use cache` directive will be available separately from the`dynamicIO` flag in the future.
...@@ -45,7 +45,7 @@ The Next.js `use cache` directive allows you to cache entire routes, components, ...@@ -45,7 +45,7 @@ The Next.js `use cache` directive allows you to cache entire routes, components,
```tsx ```tsx
// File level // File level
"use cache" 'use cache'
export default async function Page() { export default async function Page() {
// ... // ...
...@@ -53,13 +53,13 @@ export default async function Page() { ...@@ -53,13 +53,13 @@ export default async function Page() {
// Component level // Component level
export async function MyComponent() { export async function MyComponent() {
"use cache" 'use cache'
return <></> return <></>
} }
// Function level // Function level
export async function getData() { export async function getData() {
"use cache" 'use cache'
const data = await fetch('/api/data') const data = await fetch('/api/data')
return data return data
} }
...@@ -83,14 +83,14 @@ Both of these APIs integrate across the client and server caching layers, meanin ...@@ -83,14 +83,14 @@ Both of these APIs integrate across the client and server caching layers, meanin
The example below shows how to use the `cacheLife` function at the function level to set a revalidation period of one day on the functions output: The example below shows how to use the `cacheLife` function at the function level to set a revalidation period of one day on the functions output:
```tsx filename="app/components/my-component.tsx" highlight={1,5,6} ```tsx filename="app/components/my-component.tsx" highlight={1,5,6}
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
export async function MyComponent() { export async function MyComponent() {
async function getData() { async function getData() {
"use cache" 'use cache'
cacheLife('days') cacheLife('days')
const data = await fetch('/api/data'); const data = await fetch('/api/data')
return data; return data
} }
return // Use the data here return // Use the data here
...@@ -114,7 +114,7 @@ We recommend always adding a cache profile when using the `use cache` directive ...@@ -114,7 +114,7 @@ We recommend always adding a cache profile when using the `use cache` directive
Cache profiles are objects that contain the following properties: Cache profiles are objects that contain the following properties:
| **Property** | **Value** | **Description** | **Requirement** | | **Property** | **Value** | **Description** | **Requirement** |
| --- | --- | --- | --- | | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `stale` | `number` | Duration the client should cache a value without checking the server. | Optional | | `stale` | `number` | Duration the client should cache a value without checking the server. | Optional |
| `revalidate` | `number` | Frequency at which the cache should refresh on the server; stale values may be served while revalidating. | Optional | | `revalidate` | `number` | Frequency at which the cache should refresh on the server; stale values may be served while revalidating. | Optional |
| `expire` | `number` | Maximum duration for which a value can remain stale before switching to dynamic fetching; must be longer than `revalidate`. | Optional - Must be longer than `revalidate` | | `expire` | `number` | Maximum duration for which a value can remain stale before switching to dynamic fetching; must be longer than `revalidate`. | Optional - Must be longer than `revalidate` |
...@@ -128,7 +128,7 @@ The "stale" property differs from the [`staleTimes`](/docs/app/api-reference/nex ...@@ -128,7 +128,7 @@ The "stale" property differs from the [`staleTimes`](/docs/app/api-reference/nex
Next.js provides a set of named cache profiles modeled on various timescales. If you don't specify a cache profile in the `cacheLife` function alongside the `use cache` directive, Next.js will automatically apply the “default” cache profile. Next.js provides a set of named cache profiles modeled on various timescales. If you don't specify a cache profile in the `cacheLife` function alongside the `use cache` directive, Next.js will automatically apply the “default” cache profile.
| **Profile** | **Stale** | **Revalidate** | **Expire** | **Description** | | **Profile** | **Stale** | **Revalidate** | **Expire** | **Description** |
| --- | --- | --- | --- | --- | | ----------- | --------- | -------------- | -------------- | ------------------------------------------------------------------------ |
| `default` | undefined | 15 minutes | INFINITE_CACHE | Default profile, suitable for content that doesn't need frequent updates | | `default` | undefined | 15 minutes | INFINITE_CACHE | Default profile, suitable for content that doesn't need frequent updates |
| `seconds` | undefined | 1 second | 1 minute | For rapidly changing content requiring near real-time updates | | `seconds` | undefined | 1 second | 1 minute | For rapidly changing content requiring near real-time updates |
| `minutes` | 5 minutes | 1 minute | 1 hour | For content that updates frequently within an hour | | `minutes` | 5 minutes | 1 minute | 1 hour | For content that updates frequently within an hour |
...@@ -140,8 +140,8 @@ Next.js provides a set of named cache profiles modeled on various timescales. If ...@@ -140,8 +140,8 @@ Next.js provides a set of named cache profiles modeled on various timescales. If
**Basic example**: **Basic example**:
```tsx filename="app/page.tsx" highlight={4} ```tsx filename="app/page.tsx" highlight={4}
"use cache" 'use cache'
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
cacheLife('minutes') cacheLife('minutes')
``` ```
...@@ -172,8 +172,8 @@ module.exports = nextConfig ...@@ -172,8 +172,8 @@ module.exports = nextConfig
The example above caches for 14 days, checks for updates daily, and expires the cache after 14 days. You can then reference this profile throughout your application by its name: The example above caches for 14 days, checks for updates daily, and expires the cache after 14 days. You can then reference this profile throughout your application by its name:
```tsx filename="app/page.tsx" highlight={4} ```tsx filename="app/page.tsx" highlight={4}
"use cache" 'use cache'
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
cacheLife('biweekly') cacheLife('biweekly')
...@@ -196,7 +196,7 @@ const nextConfig = { ...@@ -196,7 +196,7 @@ const nextConfig = {
days: { days: {
stale: 3600, // 1 hour stale: 3600, // 1 hour
revalidate: 900, // 15 minutes revalidate: 900, // 15 minutes
expire: 86400 // 1 day expire: 86400, // 1 day
}, },
}, },
}, },
...@@ -210,13 +210,13 @@ module.exports = nextConfig ...@@ -210,13 +210,13 @@ module.exports = nextConfig
For specific use cases, you can set a custom cache profile by passing an object to the `cacheLife` function: For specific use cases, you can set a custom cache profile by passing an object to the `cacheLife` function:
```tsx filename="app/page.tsx" highlight={5,6,7} ```tsx filename="app/page.tsx" highlight={5,6,7}
"use cache" 'use cache'
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
cacheLife({ cacheLife({
stale: 3600, // 1 hour stale: 3600, // 1 hour
revalidate: 900, // 15 minutes revalidate: 900, // 15 minutes
expire: 86400 // 1 day expire: 86400, // 1 day
}) })
// rest of code // rest of code
...@@ -238,10 +238,10 @@ For example, if you add the `use cache` directive to your page, without specifyi ...@@ -238,10 +238,10 @@ For example, if you add the `use cache` directive to your page, without specifyi
```tsx filename="app/components/parent.tsx" highlight={5,6,19,20} ```tsx filename="app/components/parent.tsx" highlight={5,6,19,20}
// Parent component // Parent component
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
export async function ParentComponent() { export async function ParentComponent() {
"use cache" 'use cache'
cacheLife('days') cacheLife('days')
return ( return (
...@@ -252,10 +252,10 @@ export async function ParentComponent() { ...@@ -252,10 +252,10 @@ export async function ParentComponent() {
} }
// Child component // Child component
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
export async function ChildComponent() { export async function ChildComponent() {
"use cache" 'use cache'
cacheLife('hours') cacheLife('hours')
// This component's cache will respect the shorter 'hours' profile // This component's cache will respect the shorter 'hours' profile
...@@ -271,16 +271,16 @@ In the below example the `getData` function uses the “weeks” cache profile, ...@@ -271,16 +271,16 @@ In the below example the `getData` function uses the “weeks” cache profile,
```tsx filename="app/actions.ts" highlight={4,5} ```tsx filename="app/actions.ts" highlight={4,5}
import { import {
unstable_cacheTag as cacheTag, unstable_cacheTag as cacheTag,
unstable_cacheLife as cacheLife unstable_cacheLife as cacheLife,
} from 'next/cache' } from 'next/cache'
export async function getData() { export async function getData() {
"use cache" 'use cache'
cacheLife('weeks') cacheLife('weeks')
cacheTag('my-data') cacheTag('my-data')
const data = await fetch('/api/data'); const data = await fetch('/api/data')
return data; return data
} }
``` ```
...@@ -318,6 +318,7 @@ export default Layout({children}: {children: ReactNode}) { ...@@ -318,6 +318,7 @@ export default Layout({children}: {children: ReactNode}) {
return <div>{children}</div> return <div>{children}</div>
} }
``` ```
And in your `page.tsx` file you can add the `use cache` directive to the top of the file, and define a cache profile: And in your `page.tsx` file you can add the `use cache` directive to the top of the file, and define a cache profile:
```tsx filename="app/page.tsx" ```tsx filename="app/page.tsx"
...@@ -346,19 +347,19 @@ You can use `use cache` at the component level to cache any fetches or computati ...@@ -346,19 +347,19 @@ You can use `use cache` at the component level to cache any fetches or computati
The props are serialized and form part of the cache key. If you use the same component in multiple places in your application, the cache entry will be reused as long as the serialized props produce the same value in each instance. The props are serialized and form part of the cache key. If you use the same component in multiple places in your application, the cache entry will be reused as long as the serialized props produce the same value in each instance.
```tsx filename="app/components/bookings.tsx" highlight={4,5} ```tsx filename="app/components/bookings.tsx" highlight={4,5}
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
interface BookingsProps { interface BookingsProps {
type: string type: string
} }
export async function Bookings({type = 'massage'}: BookingsProps) { export async function Bookings({ type = 'massage' }: BookingsProps) {
"use cache" 'use cache'
cacheLife('minutes') cacheLife('minutes')
async function getBookingsData() { async function getBookingsData() {
const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`); const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
return data; return data
} }
return //... return //...
} }
...@@ -369,13 +370,13 @@ export async function Bookings({type = 'massage'}: BookingsProps) { ...@@ -369,13 +370,13 @@ export async function Bookings({type = 'massage'}: BookingsProps) {
Since you can add `use cache` to any asynchronous function you aren't limited to caching components or routes only. You might want to cache a network request or database query or compute something that is very slow. By adding `use cache` to a function containing this type of work it becomes cacheable, and when reused, will share the same cache entry. Since you can add `use cache` to any asynchronous function you aren't limited to caching components or routes only. You might want to cache a network request or database query or compute something that is very slow. By adding `use cache` to a function containing this type of work it becomes cacheable, and when reused, will share the same cache entry.
```tsx filename="app/actions.ts" highlight={4,5} ```tsx filename="app/actions.ts" highlight={4,5}
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
export async function getData() { export async function getData() {
"use cache" 'use cache'
cacheLife('minutes') cacheLife('minutes')
const data = await fetch('/api/data'); const data = await fetch('/api/data')
return data; return data
} }
``` ```
...@@ -13,7 +13,7 @@ The `use client` directive designates a component to be rendered on the **client ...@@ -13,7 +13,7 @@ The `use client` directive designates a component to be rendered on the **client
To designate a component as a Client Component, add the `use client` directive **at the top of the file**, before any imports: To designate a component as a Client Component, add the `use client` directive **at the top of the file**, before any imports:
````tsx filename="app/components/counter.tsx" highlight={1} switcher ```tsx filename="app/components/counter.tsx" highlight={1} switcher
'use client' 'use client'
import { useState } from 'react' import { useState } from 'react'
...@@ -28,9 +28,9 @@ export default function Counter() { ...@@ -28,9 +28,9 @@ export default function Counter() {
</div> </div>
) )
} }
```` ```
````jsx filename="app/components/counter.js" highlight={1} switcher ```jsx filename="app/components/counter.js" highlight={1} switcher
'use client' 'use client'
import { useState } from 'react' import { useState } from 'react'
...@@ -45,7 +45,7 @@ export default function Counter() { ...@@ -45,7 +45,7 @@ export default function Counter() {
</div> </div>
) )
} }
```` ```
## Nesting Client Components within Server Components ## Nesting Client Components within Server Components
...@@ -88,8 +88,6 @@ export default function Page() { ...@@ -88,8 +88,6 @@ export default function Page() {
} }
``` ```
## Reference ## Reference
See the [React documentation](https://react.dev/reference/rsc/use-client) for more information on `use client`. See the [React documentation](https://react.dev/reference/rsc/use-client) for more information on `use client`.
...@@ -79,7 +79,6 @@ export default function MyButton() { ...@@ -79,7 +79,6 @@ export default function MyButton() {
} }
``` ```
## Using `use server` inline ## Using `use server` inline
In the following example, `use server` is used inline at the top of a function to mark it as a [Server Function](https://19.react.dev/reference/rsc/server-functions): In the following example, `use server` is used inline at the top of a function to mark it as a [Server Function](https://19.react.dev/reference/rsc/server-functions):
...@@ -126,7 +125,10 @@ Always authenticate and authorize users before performing sensitive server-side ...@@ -126,7 +125,10 @@ Always authenticate and authorize users before performing sensitive server-side
import { db } from '@/lib/db' // Your database client import { db } from '@/lib/db' // Your database client
import { authenticate } from '@/lib/auth' // Your authentication library import { authenticate } from '@/lib/auth' // Your authentication library
export async function createUser(data: { name: string; email: string }, token: string) { export async function createUser(
data: { name: string; email: string },
token: string
) {
const user = authenticate(token) const user = authenticate(token)
if (!user) { if (!user) {
throw new Error('Unauthorized') throw new Error('Unauthorized')
...@@ -152,7 +154,6 @@ export async function createUser(data, token) { ...@@ -152,7 +154,6 @@ export async function createUser(data, token) {
} }
``` ```
## Reference ## Reference
See the [React documentation](https://react.dev/reference/rsc/use-server) for more information on `use server`. See the [React documentation](https://react.dev/reference/rsc/use-server) for more information on `use server`.
...@@ -18,22 +18,22 @@ The `cacheTag` function allows you to tag cached data for on-demand invalidation ...@@ -18,22 +18,22 @@ The `cacheTag` function allows you to tag cached data for on-demand invalidation
To use `cacheTag`, enable the [`dynamicIO` flag](/docs/app/api-reference/next-config-js/dynamicIO) in your `next.config.js` and import `cacheTag` from `next/cache`: To use `cacheTag`, enable the [`dynamicIO` flag](/docs/app/api-reference/next-config-js/dynamicIO) in your `next.config.js` and import `cacheTag` from `next/cache`:
```ts filename="next.config.ts" ```ts filename="next.config.ts"
import type { NextConfig } from 'next'; import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
experimental: { experimental: {
dynamicIO: true, dynamicIO: true,
} },
}; }
export default nextConfig; export default nextConfig
``` ```
```tsx filename="app/actions.ts" ```tsx filename="app/actions.ts"
import { unstable_cacheTag as cacheTag } from 'next/cache' import { unstable_cacheTag as cacheTag } from 'next/cache'
export async function getData() { export async function getData() {
"use cache" 'use cache'
cacheTag('my-data') cacheTag('my-data')
const data = await fetch('/api/data') const data = await fetch('/api/data')
return data return data
...@@ -62,15 +62,17 @@ export default async function submit() { ...@@ -62,15 +62,17 @@ export default async function submit() {
Tag your cached data by calling `cacheTag` within a cached function or component: Tag your cached data by calling `cacheTag` within a cached function or component:
```tsx filename="app/components/bookings.tsx" ```tsx filename="app/components/bookings.tsx"
import { unstable_cacheTag as cacheTag, unstable_cacheLife as cacheLife } from 'next/cache' import {
unstable_cacheTag as cacheTag,
unstable_cacheLife as cacheLife,
} from 'next/cache'
interface BookingsProps { interface BookingsProps {
type: string type: string
} }
export async function Bookings({type = 'massage'}: BookingsProps) { export async function Bookings({ type = 'massage' }: BookingsProps) {
"use cache" 'use cache'
cacheLife('minutes') cacheLife('minutes')
cacheTag('bookings-data') cacheTag('bookings-data')
...@@ -88,15 +90,18 @@ export async function Bookings({type = 'massage'}: BookingsProps) { ...@@ -88,15 +90,18 @@ export async function Bookings({type = 'massage'}: BookingsProps) {
You can use the data returned from an async function to tag the cache entry. You can use the data returned from an async function to tag the cache entry.
```tsx filename="app/components/bookings.tsx" ```tsx filename="app/components/bookings.tsx"
import { unstable_cacheTag as cacheTag, unstable_cacheLife as cacheLife } from 'next/cache' import {
unstable_cacheTag as cacheTag,
unstable_cacheLife as cacheLife,
} from 'next/cache'
interface BookingsProps { interface BookingsProps {
type: string type: string
} }
export async function Bookings({type = 'massage'}: BookingsProps) { export async function Bookings({ type = 'massage' }: BookingsProps) {
async function getBookingsData() { async function getBookingsData() {
"use cache" 'use cache'
cacheLife('minutes') cacheLife('minutes')
const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`) const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
cacheTag('bookings-data', data.id) cacheTag('bookings-data', data.id)
......
...@@ -18,20 +18,20 @@ module.exports = { ...@@ -18,20 +18,20 @@ module.exports = {
blog: { blog: {
stale: 3600, // 1 hour stale: 3600, // 1 hour
revalidate: 900, // 15 minutes revalidate: 900, // 15 minutes
expire: 86400 // 1 day expire: 86400, // 1 day
},
}, },
}, },
}
} }
``` ```
You can now use this custom `blog` configuration in your component, function or file as follows: You can now use this custom `blog` configuration in your component, function or file as follows:
```tsx filename="app/actions.ts" highlight={4,5} ```tsx filename="app/actions.ts" highlight={4,5}
import { unstable_cacheLife as cacheLife} from 'next/cache' import { unstable_cacheLife as cacheLife } from 'next/cache'
export async function getCachedData() { export async function getCachedData() {
"use cache" 'use cache'
cacheLife('blog') cacheLife('blog')
const data = await fetch('/api/data') const data = await fetch('/api/data')
return data return data
...@@ -43,7 +43,7 @@ export async function getCachedData() { ...@@ -43,7 +43,7 @@ export async function getCachedData() {
The configuration object has key values with the following format: The configuration object has key values with the following format:
| **Property** | **Value** | **Description** | **Requirement** | | **Property** | **Value** | **Description** | **Requirement** |
| --- | --- | --- | --- | | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `stale` | `number` | Duration the client should cache a value without checking the server. | Optional | | `stale` | `number` | Duration the client should cache a value without checking the server. | Optional |
| `revalidate` | `number` | Frequency at which the cache should refresh on the server; stale values may be served while revalidating. | Optional | | `revalidate` | `number` | Frequency at which the cache should refresh on the server; stale values may be served while revalidating. | Optional |
| `expire` | `number` | Maximum duration for which a value can remain stale before switching to dynamic fetching; must be longer than `revalidate`. | Optional - Must be longer than `revalidate` | | `expire` | `number` | Maximum duration for which a value can remain stale before switching to dynamic fetching; must be longer than `revalidate`. | Optional - Must be longer than `revalidate` |
...@@ -15,15 +15,15 @@ It is expected to be used in conjunction with [`use cache`](/docs/app/api-refere ...@@ -15,15 +15,15 @@ It is expected to be used in conjunction with [`use cache`](/docs/app/api-refere
To enable the `dynamicIO` flag, set it to `true` in the `experimental` section of your `next.config.ts` file: To enable the `dynamicIO` flag, set it to `true` in the `experimental` section of your `next.config.ts` file:
```ts filename="next.config.ts" ```ts filename="next.config.ts"
import type { NextConfig } from 'next'; import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
experimental: { experimental: {
dynamicIO: true, dynamicIO: true,
} },
}; }
export default nextConfig; export default nextConfig
``` ```
When `dynamicIO` is enabled, you can use the following cache functions and configurations: When `dynamicIO` is enabled, you can use the following cache functions and configurations:
......
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