'use client'

• Reference
  • 'use client'
  • Marking client code with 'use client'
  • Passing props from Server to Client Components
• Usage

Reference

'use client'

Add 'use client' at the top of a file to mark the code to be evaluated on the client.

'use client';

import { useState } from 'react';

export default function RichTextEditor(props) {
  // ...

When a file marked with 'use client' is imported from a Server Component, compatible bundlers will treat the module import as a boundary between server-run and client-run code.

Marking client code with 'use client'

In a React app, components are often split into separate files, or modules.

For apps that use React Server Components, the app is server-rendered by default. 'use client' marks which modules in the module dependency tree are downloaded and evaluated on the client. When a server-rendered module imports a 'use client' module, the use client module and all its transitive dependencies will be run on the client.

To better illustrate this, consider the following React Server Component app and its render and module dependency tree.

In the module dependency tree of the example app, the 'use client' directive in InspirationGenerator.js marks that module and all of its transitive dependencies as client code. Only client-marked code will be bundled, downloaded and evaluated by the client.

Irregardless if a module exports a component, like inspirations.js, if a module is transitive dependency of a 'use client' module, then it will only be evaluated on the client.

In rendering, the framework will server-render the root component and continue through the render tree, opting-out of evaluating any code imported from client-marked code.

The server-rendered portion of the render tree is then sent to the client. The client, with its client code downloaded, then completes rendering the rest of the tree.

We introduce the following definitions:

• Client Components are components in a render tree that are rendered on the client.
• Server Components are components in a render tree that are rendered on the server.

Working through the example app, App, FancyText and Copyright are all server-rendered and considered Server Components. As InspirationGenerator.js and its transitive dependencies are marked as client code, the component InspirationGenerator and its child component FancyText are Client Components.

Deep Dive

How is FancyText both a Server and a Client Component?

Show Details

By the above definitions, the component FancyText is both a Server and Client Component, how can that be?

First, let’s clarify that the term “component” is not very precise. Here are just two ways “component” can be understood:

1. A “component” can refer to a component definition.

// This is a definition of a component
function MyComponent() {
	return <p>My Component</p>
}

2. A “component” can also refer to a component usage of a definition.

import MyComponent from './MyComponent';

function App() {
	// This is a usage of a component
	return <MyComponent />;
}

Often, the imprecision is not important when explaining concepts, but in this case it is.

When we talk about Server or Client Components, we are referring to component usages. Where a component is imported and used determines if it is a Server or Client Component, with one notable exception.

• If the component is imported and used in a Client Component, then the component usage is a Client Component.
• If the component is imported and used in a Server Component, then the component usage is a Server Component.

The exception is if a component is defined in a module with a 'use client' directive. In that case, regardless of where the component is imported and used, every component usage will be a Client Component.

Looking back to the question of FancyText, it’s now clear that a render tree is a tree of component usages.

The usage of FancyText as a child of App, marks that usage as a Server Component as root components are always Server Components. When FancyText is imported and used under InspirationGenerator, that usage of FancyText is a Client Component.

This also means that the component definition for FancyText will both be evaluated on the server and also be downlaoded by the client to render its Client Component usage.

Passing props from Server to Client Components

As in any React app, parent components pass data to child components. As they are rendered in different environments, passing data from a Server Component to a Client Component requires extra consideration.

Prop values passed from a Server Component to Client Component need to be serializable.

Serializable props include:

• JavaScript primitives
• Subclasses of TypedArrays

Caveats

• It’s not necessary to add 'use client' to every file that uses client-only React features, only the files that are imported from server component files. 'use client' denotes the boundary between server-only and client code; any components further down the tree will automatically be executed on the client. In order to be rendered from server components, components exported from 'use client' files must have serializable props.
• When a 'use client' file is imported from a server file, the imported values can be rendered as a React component or passed via props to a client component. Any other use will throw an exception.
• When a 'use client' file is imported from another client file, the directive has no effect. This allows you to write client-only components that are simultaneously usable from server and client components.
• All the code in 'use client' file as well as any modules it imports (directly or indirectly) will become a part of the client module graph and must be sent to and executed by the client in order to be rendered by the browser. To reduce client bundle size and take full advantage of the server, move state (and the 'use client' directives) lower in the tree when possible, and pass rendered server components as children to client components.
• Because props are serialized across the server–client boundary, note that the placement of these directives can affect the amount of data sent to the client; avoid data structures that are larger than necessary.
• Components like a <MarkdownRenderer> that use neither server-only nor client-only features should generally not be marked with 'use client'. That way, they can render exclusively on the server when used from a server component, but they’ll be added to the client bundle when used from a client component.
• Libraries published to npm should include 'use client' on exported React components that can be rendered with serializable props that use client-only React features, to allow those components to be imported and rendered by server components. Otherwise, users will need to wrap library components in their own 'use client' files which can be cumbersome and prevents the library from moving logic to the server later. When publishing prebundled files to npm, ensure that 'use client' source files end up in a bundle marked with 'use client', separate from any bundle containing exports that can be used directly on the server.
• Client components will still run as part of server-side rendering (SSR) or build-time static site generation (SSG), which act as clients to transform React components’ initial render output to HTML that can be rendered before JavaScript bundles are downloaded. But they can’t use server-only features like reading directly from a database.
• Directives like 'use client' must be at the very beginning of a file, above any imports or other code (comments above directives are OK). They must be written with single or double quotes, not backticks. (The 'use xyz' directive format somewhat resembles the useXyz() Hook naming convention, but the similarity is coincidental.)

Usage