From 0ede00938ff707d1134ccb39ade8a479aa59736f Mon Sep 17 00:00:00 2001 From: Zack Tanner <1939140+ztanner@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:14:19 -0700 Subject: [PATCH] docs lint fixes --- .../02-api-reference/01-directives/index.mdx | 2 +- .../01-directives/use-cache.mdx | 129 +++++++++--------- .../01-directives/use-client.mdx | 12 +- .../01-directives/use-server.mdx | 15 +- .../04-functions/cacheTag.mdx | 35 +++-- .../05-next-config-js/cacheLife.mdx | 18 +-- .../05-next-config-js/dynamicIO.mdx | 14 +- 7 files changed, 115 insertions(+), 110 deletions(-) diff --git a/docs/02-app/02-api-reference/01-directives/index.mdx b/docs/02-app/02-api-reference/01-directives/index.mdx index fc836f6674354..d5542f1d4a0d2 100644 --- a/docs/02-app/02-api-reference/01-directives/index.mdx +++ b/docs/02-app/02-api-reference/01-directives/index.mdx @@ -3,4 +3,4 @@ title: Directives description: Directives are used to modify the behavior of your Next.js application. --- -The following directives are available: \ No newline at end of file +The following directives are available: diff --git a/docs/02-app/02-api-reference/01-directives/use-cache.mdx b/docs/02-app/02-api-reference/01-directives/use-cache.mdx index f667bb3177af2..e93d36e489164 100644 --- a/docs/02-app/02-api-reference/01-directives/use-cache.mdx +++ b/docs/02-app/02-api-reference/01-directives/use-cache.mdx @@ -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: ```ts filename="next.config.ts" -import type { NextConfig } from 'next'; - +import type { NextConfig } from 'next' + const nextConfig: NextConfig = { experimental: { dynamicIO: true, - } -}; - -export default nextConfig; + }, +} + +export default nextConfig ``` > The `use cache` directive will be available separately from the`dynamicIO` flag in the future. @@ -41,11 +41,11 @@ Additionally, `use cache` automatically manages complexities by tracking both in ## `use cache` directive -The Next.js `use cache` directive allows you to cache entire routes, components, and the return value of functions. When you have an asynchronous function, you can mark it as cacheable by adding `use cache` at the top of the file or inside the function scope. This informs Next.js that the return value can be cached and reused for subsequent renders. +The Next.js `use cache` directive allows you to cache entire routes, components, and the return value of functions. When you have an asynchronous function, you can mark it as cacheable by adding `use cache` at the top of the file or inside the function scope. This informs Next.js that the return value can be cached and reused for subsequent renders. ```tsx // File level -"use cache" +'use cache' export default async function Page() { // ... @@ -53,13 +53,13 @@ export default async function Page() { // Component level export async function MyComponent() { - "use cache" + 'use cache' return <> } // Function level export async function getData() { - "use cache" + 'use cache' const data = await fetch('/api/data') return data } @@ -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: ```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() { async function getData() { - "use cache" + 'use cache' cacheLife('days') - const data = await fetch('/api/data'); - return data; + const data = await fetch('/api/data') + return data } return // Use the data here @@ -113,35 +113,35 @@ We recommend always adding a cache profile when using the `use cache` directive Cache profiles are objects that contain the following properties: -| **Property** | **Value** | **Description** | **Requirement** | -| --- | --- | --- | --- | -| `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 | -| `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` | +| **Property** | **Value** | **Description** | **Requirement** | +| ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| `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 | +| `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` | The "stale" property differs from the [`staleTimes`](/docs/app/api-reference/next-config-js/staleTimes) setting in that it specifically controls client-side router caching. While `staleTimes` is a global setting that affects all instances of both dynamic and static data, the `cacheLife` configuration allows you to define "stale" times on a per-function or per-route basis. - -> **Good to know**: The “stale” property does not set the `Cache-control: max-age` header. It instead controls the client-side router cache. + +> **Good to know**: The “stale” property does not set the `Cache-control: max-age` header. It instead controls the client-side router cache. ### Default cache profiles 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** | -| --- | --- | --- | --- | --- | -| `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 | -| `minutes` | 5 minutes | 1 minute | 1 hour | For content that updates frequently within an hour | -| `hours` | 5 minutes | 1 hour | 1 day | For content that updates daily but can be slightly stale | -| `days` | 5 minutes | 1 day | 1 week | For content that updates weekly but can be a day old | -| `weeks` | 5 minutes | 1 week | 1 month | For content that updates monthly but can be a week old | -| `max` | 5 minutes | 1 month | INFINITE_CACHE | For very stable content that rarely needs updating | +| **Profile** | **Stale** | **Revalidate** | **Expire** | **Description** | +| ----------- | --------- | -------------- | -------------- | ------------------------------------------------------------------------ | +| `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 | +| `minutes` | 5 minutes | 1 minute | 1 hour | For content that updates frequently within an hour | +| `hours` | 5 minutes | 1 hour | 1 day | For content that updates daily but can be slightly stale | +| `days` | 5 minutes | 1 day | 1 week | For content that updates weekly but can be a day old | +| `weeks` | 5 minutes | 1 week | 1 month | For content that updates monthly but can be a week old | +| `max` | 5 minutes | 1 month | INFINITE_CACHE | For very stable content that rarely needs updating | **Basic example**: ```tsx filename="app/page.tsx" highlight={4} -"use cache" -import { unstable_cacheLife as cacheLife} from 'next/cache' +'use cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' cacheLife('minutes') ``` @@ -150,7 +150,7 @@ The string values used to reference cache profiles don't carry inherent meaning; ### Defining reusable cache profiles -To create a reusable cache profile, choose a name that suits your use case. You can create as many custom cache profiles as needed. Each profile can be referenced by its name as a string value passed to the `cacheLife` function. +To create a reusable cache profile, choose a name that suits your use case. You can create as many custom cache profiles as needed. Each profile can be referenced by its name as a string value passed to the `cacheLife` function. ```ts filename="next.config.ts" const 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: ```tsx filename="app/page.tsx" highlight={4} -"use cache" -import { unstable_cacheLife as cacheLife} from 'next/cache' +'use cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' cacheLife('biweekly') @@ -196,7 +196,7 @@ const nextConfig = { days: { stale: 3600, // 1 hour revalidate: 900, // 15 minutes - expire: 86400 // 1 day + expire: 86400, // 1 day }, }, }, @@ -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: ```tsx filename="app/page.tsx" highlight={5,6,7} -"use cache" -import { unstable_cacheLife as cacheLife} from 'next/cache' +'use cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' cacheLife({ stale: 3600, // 1 hour revalidate: 900, // 15 minutes - expire: 86400 // 1 day + expire: 86400, // 1 day }) // rest of code @@ -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} // Parent component -import { unstable_cacheLife as cacheLife} from 'next/cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' export async function ParentComponent() { - "use cache" + 'use cache' cacheLife('days') return ( @@ -252,10 +252,10 @@ export async function ParentComponent() { } // Child component -import { unstable_cacheLife as cacheLife} from 'next/cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' export async function ChildComponent() { - "use cache" + 'use cache' cacheLife('hours') // This component's cache will respect the shorter 'hours' profile @@ -269,18 +269,18 @@ A `cacheTag` is used in combination with [`revalidateTag`](/docs/app/api-referen In the below example the `getData` function uses the “weeks” cache profile, and defines a `cacheTag` on the functions cached output: ```tsx filename="app/actions.ts" highlight={4,5} -import { +import { unstable_cacheTag as cacheTag, - unstable_cacheLife as cacheLife + unstable_cacheLife as cacheLife, } from 'next/cache' export async function getData() { - "use cache" + 'use cache' cacheLife('weeks') cacheTag('my-data') - - const data = await fetch('/api/data'); - return data; + + const data = await fetch('/api/data') + return data } ``` @@ -288,9 +288,9 @@ You can then purge the cache on-demand using revalidateTag in another function, ```tsx filename="app/submit.ts" highlight={4,5} 'use server' - + import { revalidateTag } from 'next/cache' - + export default async function submit() { await addPost() revalidateTag('my-data') @@ -318,6 +318,7 @@ export default Layout({children}: {children: ReactNode}) { return
{children}
} ``` + 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" @@ -341,24 +342,24 @@ export default Page() { ### Caching component output with `use cache` -You can use `use cache` at the component level to cache any fetches or computations performed within that component. When you reuse the component throughout your application it can share the same cache entry as long as the props maintain the same structure. +You can use `use cache` at the component level to cache any fetches or computations performed within that component. When you reuse the component throughout your application it can share the same cache entry as long as the props maintain the same structure. 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} -import { unstable_cacheLife as cacheLife} from 'next/cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' interface BookingsProps { type: string } -export async function Bookings({type = 'massage'}: BookingsProps) { - "use cache" +export async function Bookings({ type = 'massage' }: BookingsProps) { + 'use cache' cacheLife('minutes') - + async function getBookingsData() { - const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`); - return data; + const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`) + return data } return //... } @@ -366,16 +367,16 @@ export async function Bookings({type = 'massage'}: BookingsProps) { ### Caching function output with `use cache` -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} -import { unstable_cacheLife as cacheLife} from 'next/cache' +import { unstable_cacheLife as cacheLife } from 'next/cache' export async function getData() { - "use cache" + 'use cache' cacheLife('minutes') - - const data = await fetch('/api/data'); - return data; + + const data = await fetch('/api/data') + return data } ``` diff --git a/docs/02-app/02-api-reference/01-directives/use-client.mdx b/docs/02-app/02-api-reference/01-directives/use-client.mdx index 51030a600892f..016358a0f6924 100644 --- a/docs/02-app/02-api-reference/01-directives/use-client.mdx +++ b/docs/02-app/02-api-reference/01-directives/use-client.mdx @@ -3,7 +3,7 @@ title: use client description: Learn how to use the use client directive to render a component on the client. related: description: React documentation for use client. - links: + links: - https://react.dev/reference/rsc/use-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: -````tsx filename="app/components/counter.tsx" highlight={1} switcher +```tsx filename="app/components/counter.tsx" highlight={1} switcher 'use client' import { useState } from 'react' @@ -28,9 +28,9 @@ export default function Counter() { ) } -```` +``` -````jsx filename="app/components/counter.js" highlight={1} switcher +```jsx filename="app/components/counter.js" highlight={1} switcher 'use client' import { useState } from 'react' @@ -45,7 +45,7 @@ export default function Counter() { ) } -```` +``` ## Nesting Client Components within Server Components @@ -88,8 +88,6 @@ export default function Page() { } ``` - ## Reference See the [React documentation](https://react.dev/reference/rsc/use-client) for more information on `use client`. - diff --git a/docs/02-app/02-api-reference/01-directives/use-server.mdx b/docs/02-app/02-api-reference/01-directives/use-server.mdx index 73fa1d73642e3..8b428752171ba 100644 --- a/docs/02-app/02-api-reference/01-directives/use-server.mdx +++ b/docs/02-app/02-api-reference/01-directives/use-server.mdx @@ -3,7 +3,7 @@ title: use server description: Learn how to use the use server directive to execute code on the server. related: description: React documentation for use server. - links: + links: - https://react.dev/reference/rsc/use-server --- @@ -79,14 +79,13 @@ export default function MyButton() { } ``` - ## 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): ```tsx filename="app/page.tsx" highlight={5} switcher import { db } from '@/lib/db' // Your database client - + export default function UserList() { async function fetchUsers() { 'use server' @@ -100,14 +99,14 @@ export default function UserList() { ```jsx filename="app/page.js" highlight={5} switcher import { db } from '@/lib/db' // Your database client - + export default function UserList() { async function fetchUsers() { 'use server' const users = await db.user.findMany() return users } - + return } ``` @@ -126,7 +125,10 @@ Always authenticate and authorize users before performing sensitive server-side import { db } from '@/lib/db' // Your database client 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) if (!user) { throw new Error('Unauthorized') @@ -152,7 +154,6 @@ export async function createUser(data, token) { } ``` - ## Reference See the [React documentation](https://react.dev/reference/rsc/use-server) for more information on `use server`. diff --git a/docs/02-app/02-api-reference/04-functions/cacheTag.mdx b/docs/02-app/02-api-reference/04-functions/cacheTag.mdx index 9c26f7e711dc3..46ceaf62b88a7 100644 --- a/docs/02-app/02-api-reference/04-functions/cacheTag.mdx +++ b/docs/02-app/02-api-reference/04-functions/cacheTag.mdx @@ -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`: ```ts filename="next.config.ts" -import type { NextConfig } from 'next'; - +import type { NextConfig } from 'next' + const nextConfig: NextConfig = { experimental: { dynamicIO: true, - } -}; - -export default nextConfig; + }, +} + +export default nextConfig ``` ```tsx filename="app/actions.ts" import { unstable_cacheTag as cacheTag } from 'next/cache' export async function getData() { - "use cache" + 'use cache' cacheTag('my-data') const data = await fetch('/api/data') return data @@ -62,15 +62,17 @@ export default async function submit() { Tag your cached data by calling `cacheTag` within a cached function or component: ```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 { type: string } -export async function Bookings({type = 'massage'}: BookingsProps) { - "use cache" +export async function Bookings({ type = 'massage' }: BookingsProps) { + 'use cache' cacheLife('minutes') cacheTag('bookings-data') @@ -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. ```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 { type: string } -export async function Bookings({type = 'massage'}: BookingsProps) { +export async function Bookings({ type = 'massage' }: BookingsProps) { async function getBookingsData() { - "use cache" + 'use cache' cacheLife('minutes') const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`) cacheTag('bookings-data', data.id) @@ -125,7 +130,7 @@ export async function updateBookings() { - **Idempotent Tags**: Applying the same tag multiple times has no additional effect. - **Multiple Tags**: You can assign multiple tags to a single cache entry by passing an array to `cacheTag`. - + ```tsx cacheTag(['tag-one', 'tag-two']) ``` diff --git a/docs/02-app/02-api-reference/05-next-config-js/cacheLife.mdx b/docs/02-app/02-api-reference/05-next-config-js/cacheLife.mdx index eb9eb8906bdbb..d477e6232e2f3 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/cacheLife.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/cacheLife.mdx @@ -18,20 +18,20 @@ module.exports = { blog: { stale: 3600, // 1 hour 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: ```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() { - "use cache" + 'use cache' cacheLife('blog') const data = await fetch('/api/data') return data @@ -42,8 +42,8 @@ export async function getCachedData() { The configuration object has key values with the following format: -| **Property** | **Value** | **Description** | **Requirement** | -| --- | --- | --- | --- | -| `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 | -| `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` | \ No newline at end of file +| **Property** | **Value** | **Description** | **Requirement** | +| ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| `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 | +| `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` | diff --git a/docs/02-app/02-api-reference/05-next-config-js/dynamicIO.mdx b/docs/02-app/02-api-reference/05-next-config-js/dynamicIO.mdx index fee689d2b34c9..461b93370839a 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/dynamicIO.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/dynamicIO.mdx @@ -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: ```ts filename="next.config.ts" -import type { NextConfig } from 'next'; - +import type { NextConfig } from 'next' + const nextConfig: NextConfig = { experimental: { dynamicIO: true, - } -}; - -export default nextConfig; + }, +} + +export default nextConfig ``` When `dynamicIO` is enabled, you can use the following cache functions and configurations: @@ -34,4 +34,4 @@ When `dynamicIO` is enabled, you can use the following cache functions and confi ## Notes -- While `dynamicIO` can optimize performance by ensuring fresh data fetching during runtime, it may also introduce additional latency compared to serving pre-rendered content. \ No newline at end of file +- While `dynamicIO` can optimize performance by ensuring fresh data fetching during runtime, it may also introduce additional latency compared to serving pre-rendered content.