'use client'

• Referensi
  • 'use client'
  • Bagaimana 'use client' menandai kode klien
  • When to use 'use client'
  • Serializable types returned by Server Components
• Usage
  • Building with interactivity and state
  • Using client APIs
  • Using third-party libraries

Referensi

'use client'

Tambahkan 'use client' di bagian atas file untuk menandai modul dan dependensi transitifnya sebagai kode klien.

'use client';

import { useState } from 'react';
import { formatDate } from './formatters';
import Button from './button';

export default function RichTextEditor({ timestamp, text }) {
  const date = formatDate(timestamp);
  // ...
  const editButton = <Button />;
  // ...
}

Saat file yang ditandai dengan 'use client' diimpor dari Komponen Server, bundler yang kompatibel akan memperlakukan impor modul sebagai batas antara kode yang dijalankan server dan kode yang dijalankan klien.

Sebagai dependensi RichTextEditor, formatDate dan Button juga akan dievaluasi pada klien terlepas dari apakah modulnya berisi direktif 'use client'. Perhatikan bahwa satu modul dapat dievaluasi pada server saat diimpor dari kode server dan pada klien saat diimpor dari kode klien.

Catatan penting

• 'use client' harus berada di awal file, di atas impor atau kode lain (komentar tidak masalah). Direktif harus ditulis dengan tanda kutip tunggal atau ganda, tetapi tidak dengan tanda kutip terbalik.
• Saat modul 'use client' diimpor dari modul lain yang dirender klien, direktif tersebut tidak memiliki efek.
• Saat modul komponen berisi direktif 'use client', penggunaan komponen tersebut dijamin sebagai Komponen Klien. Namun, komponen tetap dapat dievaluasi pada klien meskipun tidak memiliki direktif 'use client'.
  • Penggunaan komponen dianggap sebagai Komponen Klien jika didefinisikan dalam modul dengan direktif 'use client' atau saat merupakan dependensi transitif dari modul yang berisi direktif 'use client'. Jika tidak, maka merupakan Komponen Server.
• Kode yang ditandai untuk evaluasi klien tidak terbatas pada komponen. Semua kode yang merupakan bagian dari sub-pohon modul Klien dikirim ke dan dijalankan oleh klien.
• Ketika modul yang dievaluasi server mengimpor nilai dari modul 'use client', nilai tersebut harus berupa komponen React atau nilai prop serialisasi yang didukung untuk diteruskan ke Komponen Klien. Kasus penggunaan lainnya akan memunculkan pengecualian.

Bagaimana 'use client' menandai kode klien

Dalam aplikasi React, komponen sering dibagi menjadi file terpisah, atau modul.

Untuk aplikasi yang menggunakan Komponen Server React, aplikasi dirender di server secara bawaan. 'use client' memperkenalkan batasan server-client di pohon dependensi modul, yang secara efektif menciptakan subpohon modul Klien.

Untuk mengilustrasikan hal ini dengan lebih baik, perhatikan aplikasi Komponen Server React berikut.

Pada pohon dependensi modul aplikasi contoh ini, direktif 'use client' dalam InspirationGenerator.js menandai modul tersebut dan semua dependensi transitifnya sebagai modul Klien. Subpohon yang dimulai pada InspirationGenerator.js sekarang ditandai sebagai modul Klien.

Selama proses render, framework akan melakukan server-render pada komponen root dan melanjutkan melalui pohon render, dengan memilih untuk tidak mengevaluasi kode apa pun yang diimpor dari kode yang ditandai klien.

Bagian pohon render yang dirender server kemudian dikirim ke klien. Klien, dengan kode klien yang diunduh, kemudian menyelesaikan rendering sisa pohon.

Kami memperkenalkan definisi berikut:

• Komponen Klien adalah komponen dalam pohon render yang dirender pada klien.
• Komponen Server adalah komponen dalam pohon render yang dirender pada server.

Saat menelusuri aplikasi contoh, App, FancyText, dan Copyright semuanya dirender oleh server dan dianggap sebagai Komponen Server. Karena InspirationGenerator.js dan dependensi transitifnya ditandai sebagai kode klien, komponen InspirationGenerator dan komponen turunannya FancyText adalah Komponen Klien.

Pendalaman

Bagaimana caranya FancyText menjadi Komponen Server dan Klien sekaligus?

Tampilkan Detil

Berdasarkan definisi di atas, komponen FancyText merupakan Komponen Server dan Klien, bagaimana mungkin?

Pertama, mari kita perjelas bahwa istilah “komponen” tidak terlalu tepat. Berikut ini hanya dua cara “komponen” dapat dipahami:

1. “Komponen” dapat merujuk ke definisi komponen. Dalam kebanyakan kasus, ini akan menjadi fungsi.

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

2. ”Komponen” juga dapat merujuk pada penggunaan komponen dari definisinya.

import MyComponent from './MyComponent';

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

Seringkali, ketidaktepatan tidaklah penting saat menjelaskan konsep, tetapi dalam kasus ini penting.

Saat kita berbicara tentang Komponen Server atau Klien, kita mengacu pada penggunaan komponen.

• Jika komponen didefinisikan dalam modul dengan direktif 'use client', atau komponen diimpor dan dipanggil dalam Komponen Klien, maka penggunaan komponen tersebut adalah Komponen Klien.
• Jika tidak, penggunaan komponen tersebut adalah Komponen Server.

Kembali ke pertanyaan tentang FancyText, kita melihat bahwa definisi komponen tidak memiliki direktif 'use client' dan memiliki dua penggunaan.

Penggunaan FancyText sebagai anak dari App, menandai penggunaan tersebut sebagai Komponen Server. Ketika FancyText diimpor dan dipanggil di bawah InspirationGenerator, penggunaan FancyText tersebut adalah Komponen Klien karena InspirationGenerator berisi direktif 'use client'.

Ini berarti bahwa definisi komponen untuk FancyText akan dievaluasi di server dan juga diunduh oleh klien untuk merender penggunaan Komponen Kliennya.

Pendalaman

Mengapa Copyright merupakan Komponen Server?

Tampilkan Detil

Karena Copyright ditampilkan sebagai anak dari Komponen Klien InspirationGenerator, Anda mungkin terkejut bahwa itu adalah Komponen Server.

Ingat bahwa 'use client' mendefinisikan batas antara kode server dan klien pada pohon dependensi modul, bukan pohon render.

Dalam pohon dependensi modul, kita melihat bahwa App.js mengimpor dan memanggil Copyright dari modul Copyright.js. Karena Copyright.js tidak berisi direktif 'use client', penggunaan komponen dirender di server. App dirender di server karena merupakan komponen akar.

Komponen Klien dapat merender Komponen Server karena Anda dapat meneruskan JSX sebagai properti. Dalam kasus ini, InspirationGenerator menerima Copyright sebagai anak. Namun, modul InspirationGenerator tidak pernah secara langsung mengimpor modul Copyright atau memanggil komponen, semua itu dilakukan oleh App. Faktanya, komponen Copyright dieksekusi sepenuhnya sebelum InspirationGenerator mulai merender.

Kesimpulannya adalah hubungan render induk-anak antara komponen tidak menjamin lingkungan render yang sama.

When to use 'use client'

With 'use client', you can determine when components are Client Components. As Server Components are default, here is a brief overview of the advantages and limitations to Server Components to determine when you need to mark something as client rendered.

For simplicity, we talk about Server Components, but the same principles apply to all code in your app that is server run.

Advantages of Server Components

• Server Components can reduce the amount of code sent and run by the client. Only Client modules are bundled and evaluated by the client.
• Server Components benefit from running on the server. They can access the local filesystem and may experience low latency for data fetches and network requests.

Limitations of Server Components

• Server Components cannot support interaction as event handlers must be registered and triggered by a client.
  • For example, event handlers like onClick can only be defined in Client Components.
• Server Components cannot use most Hooks.
  • When Server Components are rendered, their output is essentially a list of components for the client to render. Server Components do not persist in memory after render and cannot have their own state.

Serializable types returned by Server 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 must be serializable.

Serializable props include:

• Primitives
  • string
  • number
  • bigint
  • boolean
  • undefined
  • null
  • symbol, only symbols registered in the global Symbol registry via Symbol.for
• Iterables containing serializable values
  • String
  • Array
  • Map
  • Set
  • TypedArray and ArrayBuffer
• Date
• Plain objects: those created with object initializers, with serializable properties
• Functions that are Server Functions
• Client or Server Component elements (JSX)
• Promises

Notably, these are not supported:

• Functions that are not exported from client-marked modules or marked with 'use server'
• Classes
• Objects that are instances of any class (other than the built-ins mentioned) or objects with a null prototype
• Symbols not registered globally, ex. Symbol('my new symbol')

Usage

Building with interactivity and state

As Counter requires both the useState Hook and event handlers to increment or decrement the value, this component must be a Client Component and will require a 'use client' directive at the top.

In contrast, a component that renders UI without interaction will not need to be a Client Component.

import { readFile } from 'node:fs/promises';
import Counter from './Counter';

export default async function CounterContainer() {
  const initialValue = await readFile('/path/to/counter_value');
  return <Counter initialValue={initialValue} />
}

For example, Counter’s parent component, CounterContainer, does not require 'use client' as it is not interactive and does not use state. In addition, CounterContainer must be a Server Component as it reads from the local file system on the server, which is possible only in a Server Component.

There are also components that don’t use any server or client-only features and can be agnostic to where they render. In our earlier example, FancyText is one such component.

export default function FancyText({title, text}) {
  return title
    ? <h1 className='fancy title'>{text}</h1>
    : <h3 className='fancy cursive'>{text}</h3>
}

In this case, we don’t add the 'use client' directive, resulting in FancyText’s output (rather than its source code) to be sent to the browser when referenced from a Server Component. As demonstrated in the earlier Inspirations app example, FancyText is used as both a Server or Client Component, depending on where it is imported and used.

But if FancyText’s HTML output was large relative to its source code (including dependencies), it might be more efficient to force it to always be a Client Component. Components that return a long SVG path string are one case where it may be more efficient to force a component to be a Client Component.

Using client APIs

Your React app may use client-specific APIs, such as the browser’s APIs for web storage, audio and video manipulation, and device hardware, among others.

In this example, the component uses DOM APIs to manipulate a canvas element. Since those APIs are only available in the browser, it must be marked as a Client Component.

'use client';

import {useRef, useEffect} from 'react';

export default function Circle() {
  const ref = useRef(null);
  useLayoutEffect(() => {
    const canvas = ref.current;
    const context = canvas.getContext('2d');
    context.reset();
    context.beginPath();
    context.arc(100, 75, 50, 0, 2 * Math.PI);
    context.stroke();
  });
  return <canvas ref={ref} />;
}

Using third-party libraries

Often in a React app, you’ll leverage third-party libraries to handle common UI patterns or logic.

These libraries may rely on component Hooks or client APIs. Third-party components that use any of the following React APIs must run on the client:

• createContext
• react and react-dom Hooks, excluding use and useId
• forwardRef
• memo
• startTransition
• If they use client APIs, ex. DOM insertion or native platform views

If these libraries have been updated to be compatible with React Server Components, then they will already include 'use client' markers of their own, allowing you to use them directly from your Server Components. If a library hasn’t been updated, or if a component needs props like event handlers that can only be specified on the client, you may need to add your own Client Component file in between the third-party Client Component and your Server Component where you’d like to use it.