`use client` ディレクティブ¶

See the React documentation for more information on use client.

use client ディレクティブは、クライアント側でレンダリングされるコンポーネントを指定します。これは、状態管理、イベント処理、ブラウザ API へのアクセスなど、クライアント側の JavaScript 機能を必要とするインタラクティブなユーザーインターフェイス (UI) を作成するときに使用する必要があります。これは React の機能です。

デフォルトでは、すべてのコンポーネントは サーバーコンポーネント として扱われます。クライアントでのインタラクティブなレンダリング（例：useStateやuseEffectを使った状態管理）を必要とするコンポーネントには、このディレクティブを使用してクライアントコンポーネントであることを指定します。

使用例¶

コンポーネントをクライアントコンポーネントとして指定するには、インポートの前に、ファイルの先頭に use client ディレクティブを追加します。

// client-component.js
"use client";

import { useState } from 'react';

export default function ClientComponent() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

サーバーコンポーネント内にクライアントコンポーネントをネストする¶

サーバーコンポーネントとクライアントコンポーネントを組み合わせると、パフォーマンスとインタラクティブ性の両方を備えたアプリケーションを構築できます。

サーバーコンポーネント: 静的コンテンツ、データ取得、SEO に適した要素に使用します。
クライアントコンポーネント: 状態、効果、またはブラウザー API を必要とするインタラクティブ要素に使用します。
コンポーネントの構成: サーバーコンポーネント内にクライアントコンポーネントを必要に応じてネストし、サーバーロジックとクライアントロジックを明確に分離します。

次の例では、

ヘッダーは静的コンテンツを処理するサーバーコンポーネントです。 カウンターはページ内でのインタラクティブ性を可能にするクライアントコンポーネントです。

import Header from './header'
import Counter from './counter' // This is a Client Component

export default function Page() {
  return (
    <div>
      <Header />
      <Counter />
    </div>
  )
}

Note

「use client」は、React Server Components を使用している場合、またはそれらと互換性のあるライブラリを構築している場合にのみ必要です。

「use client」とマークされたファイルがサーバーコンポーネントからインポートされると、互換性のあるバンドラーはモジュールのインポートをサーバー実行コードとクライアント実行コードの間の境界として扱います。

RichTextEditor の依存関係として、formatDate および Button も、モジュールに「use client」ディレクティブが含まれているかどうかに関係なく、クライアントで評価されます。サーバーコードからインポートされた場合はサーバーで、クライアントコードからインポートされた場合はクライアントで、単一のモジュールが評価される可能性があることに注意してください。

注意点¶

'use client' は、ファイルの先頭、インポートやその他のコードより上になければなりません (コメントは OK)。これらは、一重引用符または二重引用符で記述する必要がありますが、バックティックは使用できません。
'use client' モジュールが別のクライアントレンダリングモジュールからインポートされた場合、ディレクティブは効果がありません。
コンポーネントモジュールに 'use client' ディレクティブが含まれている場合、そのコンポーネントの使用はクライアントコンポーネントであることが保証されます。ただし、コンポーネントは 'use client' ディレクティブがなくてもクライアントで評価できます。
コンポーネントの使用は、モジュールで 'use client' ディレクティブを使用して定義されている場合、または 'use client' ディレクティブを含むモジュールの推移的な依存関係である場合に、クライアントコンポーネントと見なされます。それ以外の場合は、サーバーコンポーネントです。
クライアント評価用にマークされたコードは、コンポーネントに限定されません。クライアントモジュールサブツリーの一部であるすべてのコードは、クライアントに送信され、クライアントによって実行されます。
サーバー評価モジュールが 'use client' モジュールから値をインポートする場合、値は React コンポーネントか、クライアントコンポーネントに渡されるサポートされているシリアル化可能なプロパティ値のいずれかである必要があります。その他の使用例では例外がスローされます。

「use client」がクライアントコードをマークする方法¶

React アプリでは、コンポーネントは多くの場合、個別のファイルまたはモジュールに分割されます。

React Server Components を使用するアプリの場合、アプリはデフォルトでサーバーレンダリングされます。「use client」は、モジュール依存関係ツリーにサーバーとクライアントの境界を導入し、実質的にクライアントモジュールのサブツリーを作成します。

これをわかりやすく説明するために、次の React Server Components アプリを考えてみましょう。

How 'use client' marks client code

このサンプルアプリのモジュール依存関係ツリーでは、InspirationGenerator.js の 'use client' ディレクティブによって、そのモジュールとそのすべての推移的依存関係がクライアントモジュールとしてマークされます。InspirationGenerator.js から始まるサブツリーは、クライアントモジュールとしてマークされるようになりました。

alt text

「use client」は、React Server Components アプリのモジュール依存関係ツリーをセグメント化し、InspirationGenerator.js とそのすべての依存関係をクライアントレンダリングとしてマークします。

レンダリング中、フレームワークはルートコンポーネントをサーバーレンダリングし、クライアントでマークされたコードからインポートされたコードの評価をオプトアウトして、レンダリングツリーを続行します。

次に、レンダリングツリーのサーバーレンダリングされた部分がクライアントに送信されます。クライアントは、クライアントコードをダウンロードして、ツリーの残りの部分のレンダリングを完了します。

alt text

React サーバーコンポーネントアプリのレンダリングツリー。InspirationGenerator とその子コンポーネント FancyText は、クライアントマークコードからエクスポートされたコンポーネントであり、クライアントコンポーネントと見なされます。

以下の定義を紹介します:

クライアントコンポーネントは、クライアントでレンダリングされるレンダリングツリー内のコンポーネントです。
サーバーコンポーネントは、サーバーでレンダリングされるレンダリングツリー内のコンポーネントです。サンプルアプリで作業すると、App、FancyText、Copyright はすべてサーバーでレンダリングされ、サーバーコンポーネントと見なされます。InspirationGenerator.js とその推移的な依存関係はクライアントコードとしてマークされているため、コンポーネント InspirationGenerator とその子コンポーネント FancyText はクライアントコンポーネントです。

When to use 'use client'¶

「クライアントの使用」を使用すると、コンポーネントがクライアントコンポーネントであるかどうかを判断できます。サーバーコンポーネントはデフォルトであるため、クライアントレンダリングとしてマークする必要があるものを判断できるように、サーバーコンポーネントの利点と制限について簡単に説明します。

わかりやすくするために、サーバーコンポーネントについて説明しますが、同じ原則が、サーバーで実行されるアプリのすべてのコードに適用されます。

サーバーコンポーネントの利点¶

サーバーコンポーネントを使用すると、クライアントによって送信および実行されるコードの量を削減できます。クライアントモジュールのみがバンドルされ、クライアントによって評価されます。
サーバーコンポーネントは、サーバー上で実行することでメリットを得られます。ローカルファイルシステムにアクセスでき、データ取得やネットワーク要求の待ち時間が短くなる可能性があります。

サーバーコンポーネントの制限¶

サーバーコンポーネントは、イベントハンドラーをクライアントが登録してトリガーする必要があるため、インタラクションをサポートできません。たとえば、onClick などのイベントハンドラーは、クライアントコンポーネントでのみ定義できます。
サーバーコンポーネントは、ほとんどのフックを使用できません。サーバーコンポーネントがレンダリングされると、その出力は基本的に、クライアントがレンダリングするコンポーネントのリストになります。サーバーコンポーネントは、レンダリング後にメモリ内に保持されず、独自の状態を持つことはできません。

サーバーコンポーネントによって返されるシリアル化可能な型¶

他の React アプリと同様に、親コンポーネントは子コンポーネントにデータを渡します。これらは異なる環境でレンダリングされるため、サーバーコンポーネントからクライアントコンポーネントにデータを渡すには特別な考慮が必要です。
サーバーコンポーネントからクライアントコンポーネントに渡されるプロパティ値はシリアル化可能である必要があります。

シリアル化可能なプロパティには次のものが含まれます。

Serializable types returned by Server Components

Usage¶

インタラクティブ性と状態を備えた構築¶

'use client';

import { useState } from 'react';

export default function Counter({initialValue = 0}) {
  const [countValue, setCountValue] = useState(initialValue);
  const increment = () => setCountValue(countValue + 1);
  const decrement = () => setCountValue(countValue - 1);
  return (
    <>
      <h2>Count Value: {countValue}</h2>
      <button onClick={increment}>+1</button>
      <button onClick={decrement}>-1</button>
    </>
  );
}

Counter では、値を増減するために useState フックとイベントハンドラーの両方が必要なので、このコンポーネントはクライアントコンポーネントである必要があり、先頭に 'use client' ディレクティブが必要です。

対照的に、インタラクションなしで UI をレンダリングするコンポーネントは、クライアントコンポーネントである必要はありません。

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} />
}

たとえば、Counter の親コンポーネントである CounterContainer は、インタラクティブではなく状態も使用しないため、「クライアントの使用」は必要ありません。さらに、CounterContainer はサーバー上のローカルファイルシステムから読み取るため、サーバーコンポーネントである必要があります。これは、サーバーコンポーネントでのみ可能です。

サーバーまたはクライアントのみの機能を使用せず、レンダリングする場所に依存しないコンポーネントもあります。前の例では、FancyText がそのようなコンポーネントの 1 つです。

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

この場合、「use client」ディレクティブを追加しないため、サーバーコンポーネントから参照されたときに、FancyText の出力 (ソースコードではなく) がブラウザーに送信されます。以前の Inspirations アプリの例で示したように、FancyText は、インポートされて使用される場所に応じて、サーバーコンポーネントまたはクライアントコンポーネントの両方として使用されます。

ただし、FancyText の HTML 出力がソースコード (依存関係を含む) に比べて大きい場合は、常にクライアントコンポーネントになるように強制する方が効率的である可能性があります。長い SVG パス文字列を返すコンポーネントは、コンポーネントをクライアントコンポーネントに強制する方が効率的である可能性がある 1 つのケースです。

Using client APIs¶

React アプリでは、Web ストレージ、オーディオとビデオの操作、デバイスハードウェアなどのブラウザ API など、クライアント固有の API が使用される場合があります。

この例では、コンポーネントは DOM API を使用してキャンバス要素を操作します。これらの API はブラウザでのみ使用できるため、クライアントコンポーネントとしてマークする必要があります。

'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¶

React アプリでは、一般的な UI パターンやロジックを処理するためにサードパーティのライブラリを利用することがよくあります。

これらのライブラリは、コンポーネントフックまたはクライアント API に依存する場合があります。次の React API のいずれかを使用するサードパーティコンポーネントは、クライアントで実行する必要があります。

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

これらのライブラリが React サーバーコンポーネントと互換性を持つように更新されている場合、それらには既に独自の「クライアント使用」マーカーが含まれているため、サーバーコンポーネントから直接使用できます。ライブラリが更新されていない場合、またはコンポーネントがクライアントでのみ指定できるイベントハンドラーなどのプロパティを必要とする場合は、サードパーティのクライアントコンポーネントと、使用するサーバーコンポーネントの間に独自のクライアントコンポーネントファイルを追加する必要があります。

use client ディレクティブ¶