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

docs: server client and directives (#96145)

- Enrich the directives entry point
- New guide for Server and Client components. Conceptual backing for the
getting started page.

---------
Co-authored-by: 's avatarAurora Scharff <aurora.sofie@gmail.com>
parent bbec4fe2
......@@ -6,12 +6,15 @@ related:
description: Learn more about the APIs mentioned in this page.
links:
- app/api-reference/directives/use-client
- app/guides/server-and-client-boundary
---
By default, layouts and pages are [Server Components](https://react.dev/reference/rsc/server-components), which lets you fetch data and render parts of your UI on the server, optionally cache the result, and stream it to the client. When you need interactivity or browser APIs, you can use [Client Components](https://react.dev/reference/rsc/use-client) to layer in functionality.
This page explains how Server and Client Components work in Next.js and when to use them, with examples of how to compose them together in your application.
> **Good to know:** For an explanation of where each component type runs and how the boundary works, see [The Server and Client Boundary](/docs/app/guides/server-and-client-boundary).
## When to use Server and Client Components?
The client and server environments have different capabilities. Server and Client Components allow you to run logic in each environment depending on your use case.
......@@ -106,7 +109,7 @@ On the server, Next.js uses React's APIs to orchestrate rendering. The rendering
> **What is the React Server Component Payload (RSC)?**
>
> The RSC Payload is a compact binary representation of the rendered React Server Components tree. It's used by React on the client to update the browser's DOM. The RSC Payload contains:
> The RSC Payload is a compact, serialized representation of the rendered React Server Components tree. It's used by React on the client to update the browser's DOM. The RSC Payload contains:
>
> - The rendered result of Server Components
> - Placeholders for where Client Components should be rendered and references to their JavaScript files
......@@ -183,7 +186,7 @@ See [Interleaving Server and Client Components](/docs/app/getting-started/server
To reduce the size of your client JavaScript bundles, add `'use client'` to specific interactive components instead of marking large parts of your UI as Client Components.
For example, the `<Layout>` component contains mostly static elements like a logo and navigation links, but includes an interactive search bar. `<Search />` is interactive and needs to be a Client Component, however, the rest of the layout can remain a Server Component.
For example, the `<Layout>` component contains mostly static elements like a logo and navigation links, but includes an interactive search bar. `<Search />` needs to be a Client Component, while the rest of the layout can stay a Server Component.
```tsx filename="app/layout.tsx" highlight={12} switcher
// Client Component
......
This diff is collapsed.
---
title: Directives
description: Directives are used to modify the behavior of your Next.js application.
description: Learn how React and Next.js directives define client entry points, Server Functions, and cached output.
---
The following directives are available:
Directives are string literals that tell the compiler and bundler how to treat the code around them. On their own, directives look like plain strings, but Next.js and React read them as instructions that transform the code they cover. A directive can create a client entry point or a Server Function, or cache a function's or component's output.
| Directive | Defined by | Effect |
| --------------------------------------------------------------- | ---------- | --------------------------------------------------- |
| [`'use client'`](/docs/app/api-reference/directives/use-client) | React | Creates a client entry point from Server Components |
| [`'use server'`](/docs/app/api-reference/directives/use-server) | React | Exposes server-side functions as Server Functions |
| [`'use cache'`](/docs/app/api-reference/directives/use-cache) | Next.js | Caches and reuses output based on the code's inputs |
The `'use cache'` directive also has [`'use cache: remote'`](/docs/app/api-reference/directives/use-cache-remote) and [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) variants. Configure custom [cache handlers](/docs/app/api-reference/config/next-config-js/cacheHandlers) to control where cached entries are stored.
> **Good to know:** Next.js applies directives during compilation in both development and production.
>
> The error overlay, indicators, and stack traces point to your source file and line rather than the generated output.
## Where to place a directive
The `'use client'` directive must appear at the top of a file, before any imports. It applies to the entire module and defines a file-wide boundary because the module is bundled and shipped to the browser. You cannot use `'use client'` inline.
Place `'use server'` or `'use cache'` at the top of a file to apply the directive to every export. Place either directive at the top of a function to apply it only to that function.
```ts filename="app/data.ts" switcher
// File-level: applies to every export
'use cache'
export async function getUser(id: string) {
return { id }
}
```
```js filename="app/data.js" switcher
// File-level: applies to every export
'use cache'
export async function getUser(id) {
return { id }
}
```
```tsx filename="app/user.tsx" switcher
// Function-level: applies to this function only
export async function User() {
'use cache'
return <p>User</p>
}
```
```jsx filename="app/user.js" switcher
// Function-level: applies to this function only
export async function User() {
'use cache'
return <p>User</p>
}
```
Declare `'use server'` and `'use cache'` in server modules, not in a `'use client'` module.
To import a `'use server'` or `'use cache'` function into a Client Component, place the directive at the top of the server module. The Client Component receives a reference that invokes the function on the server.
Place the directive inside a function when it should apply only to that function or component. When it should apply to several exported functions, place it at the top of the file instead of repeating it.
Every exported function covered by a file-level `'use server'` or `'use cache'` directive must be `async`.
## What each directive requires
A directive imposes rules on the code it covers:
- **`'use client'`** marks its exports as the boundary between server and client. Client Component props that cross the boundary must be [serializable](https://react.dev/reference/rsc/use-client#serializable-types). Ordinary functions, such as event handlers, cannot cross, but Server Functions can cross as references.
- **`'use server'`** marks the functions it covers as [Server Functions](/docs/app/glossary#server-function). Server Functions must be `async`. When invoked from a Client Component, their arguments and return values are serialized across the network. The Client Component receives a reference that invokes the function on the server, not the function's code.
- **`'use cache'`** caches the output of the functions or components it covers based on their inputs. Cached functions and components must be `async`. Their arguments and return values must be serializable, except for non-serializable values that the cached code passes through without inspecting. Cached code cannot read request-time APIs like `cookies()`, `headers()`, or `searchParams` directly.
File-level directive rules also apply to framework exports. With `'use cache'` at the top of a page or layout file, exported functions such as `generateMetadata` and `generateStaticParams` must be `async`. A file-level `'use cache'` directive does not allow non-function exports.
## Placement decides what you cache
With `'use cache'`, placement determines the scope of a cache entry. A directive at the top of a page caches the page's output and the components it imports. The same directive inside a data function caches only that function's result. When one data request performs the expensive work, cache that function instead of the page.
With [`'use cache: remote'`](/docs/app/api-reference/directives/use-cache-remote), a remote cache handler stores entries. Larger entries can increase storage and network costs.
......@@ -7,7 +7,7 @@ The `'use client'` directive declares an entry point for the components to be re
> **Good to know:**
>
> You do not need to add the `'use client'` directive to every file that contains Client Components. You only need to add it to the files whose components you want to render directly within Server Components. The `'use client'` directive defines the client-server [boundary](https://nextjs.org/docs/app/getting-started/server-and-client-components#using-client-components), and the components exported from such a file serve as entry points to the client.
> You do not need to add the `'use client'` directive to every file that contains Client Components. You only need to add it to the files whose components you want to render directly within Server Components. The `'use client'` directive defines the [server and client boundary](/docs/app/guides/server-and-client-boundary), and the components exported from such a file serve as entry points to the client.
## Usage
......
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