useSyncExternalStore

const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)

• リファレンス
  • useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)
• 使用法
  • 外部ストアへ�?サブスクライブ
  • ブラウザ API へ�?サブスクライブ
  • ロジックをカスタムフックに抽出する
  • サーバーレンダリング�?サポートを追加する
• トラブルシューティング
  • “The result of getSnapshot should be cached” というエラーが出る
  • subscribe が毎レンダーごとに呼び出される

リファレンス

useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)

外部データストアから値を読み取るために、コンポーネント�?トップレベルで useSyncExternalStore を呼び出します。

import { useSyncExternalStore } from 'react';
import { todosStore } from './todoStore.js';

function TodosApp() {
  const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);
  // ...
}

これは、ストアにあるデータ�?スナップショットを返します。引数として 2 つ�?関数を渡す必要があります：

1. subscribe 関数はストアへ�?サブスクライブを開始します。サブスクライブを解除する関数を返す必要があります。
2. getSnapshot 関数は、ストアからデータ�?スナップショットを読み取る必要があります。

さらに例を見る

引数

• subscribe: ストアにサブスクライブを開始し、また callback 引数を受け取る関数。ストアが変更された際に渡された callback を呼び出す必要があります。これにより、コンポーネントが再レンダーされます。subscribe 関数は、サブスクリプションをクリーンアップする関数を返す必要があります。

• getSnapshot: コンポーネントが必要とするストアにあるデータ�?スナップショットを返す関数。ストアが変更されていない場合、getSnapshot へ�?再呼び出しは同じ値を返す必要があります。ストアが変更されて返された値が（Object.is で比較して）異なる場合、React はコンポーネントを再レンダーします。

• 省略可能 getServerSnapshot: ストア�?データ�?初期スナップショットを返す関数。これはサーバレンダリング中、およびクライアント上で�?サーバレンダリングされたコンテンツ�?ハイドレーション中に�?み使用されます。サーバスナップショットはクライアントとサーバ間で同一でなければならず、通常はサーバからクライアントに渡されるシリアライズされたも�?です。こ�?引数を省略すると、サーバ上で�?コンポーネント�?レンダリングはエラーを発生させます。

返り値

レンダリングロジックで使用できるストア�?現在�?スナップショット。

注意点

• getSnapshot によって返されるストア�?スナップショットはイミュータブル（immutable; 書き換え不能）でなければなりません。背後で使っているストアがミュータブルなデータを持っている場合、データが変更された場合は新しいイミュータブルなスナップショットを返し、それ以外�?場合はキャッシュされた最後�?スナップショットを返すようにします。

• 再レンダー中に異なる subscribe 関数が渡された場合、React は新しく渡された subscribe 関数を使ってストアに再サブスクライブします。これを防ぐには、subscribe をコンポーネント�?外で�?�言します。

• ノンブロッキング型�?トランジション更新�?最中にストア�?書き換えが発生した場合、React はそ�?更新をブロッキング型で行うようにフォールバックします。具体的には、React は DOM に更新を適用する前に getSnapshot を再度呼び出します。そこで最初�?値とは異なる値が返された場合、React はトランジション�?更新を最初からやり直しますが、再試行時にはブロッキング型�?更新を行うことで、画面上�?全コンポーネントがストアから�?同一バージョン�?値を反映していることを保証します。

• useSyncExternalStore から返される値に基づいてレンダーをサスペンドさせることは推奨されていません。外部ストアで起きた変更はノンブロッキング型�?トランジション更新としてマークすることができないため、直近�? Suspense フォールバックが起動してしまいます。既に画面上に表示されているコンテンツがローディングスピナで隠れてしまうため、通常は望ましくないユーザ体験につながります。

  例えば以下�?ようなコードは推奨されません。

  const LazyProductDetailPage = lazy(() => import('./ProductDetailPage.js'));
  
  function ShoppingApp() {
    const selectedProductId = useSyncExternalStore(...);
  
    // ❌ Calling `use` with a Promise dependent on `selectedProductId`
    const data = use(fetchItem(selectedProductId))
  
    // ❌ Conditionally rendering a lazy component based on `selectedProductId`
    return selectedProductId != null ? <LazyProductDetailPage /> : <FeaturedProducts />;
  }

使用法

外部ストアへ�?サブスクライブ

React コンポーネント�?ほとんどは、props、state およびコンテクストから�?みデータを読み取ります。しかし、コンポーネントは時間と共に変化する React 外�?ストアからデータを読み取る必要がある場合があります。これには以下�?ようなも�?が含まれます：

• React �?外部で状態を保持するサードパーティ�?状態�?�理ライブラリ。
• 可変�?値を、そ�?変更にサブスクライブするため�?イベントともに公開するブラウザ API。

外部データストアから値を読み取るために、コンポーネント�?最上位で useSyncExternalStore を呼び出します。

import { useSyncExternalStore } from 'react';
import { todosStore } from './todoStore.js';

function TodosApp() {
  const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);
  // ...
}

これはストア内�?データ�?スナップショットを返します。引数として 2 つ�?関数を渡す必要があります：

1. subscribe 関数は、ストアへ�?サブスクライブを行い、またサブスクライブを解除する関数を返します。
2. getSnapshot 関数は、ストアからデータ�?スナップショットを読み取ります。

React はこれら�?関数を使ってコンポーネントをストアにサブスクライブされた状態に保ち、変更があるたびに再レンダーします。

例えば、以下�?サンドボックスでは、todosStore は React �?外部にデータを保存する外部ストアとして�?�装されています。TodosApp コンポーネントは、useSyncExternalStore フックを使ってそ�?外部ストアに接続します。

ブラウザ API へ�?サブスクライブ

useSyncExternalStore を追加するもう 1 つ�?理由は、時間とともに変化する、ブラウザが公開する値にサブスクライブしたい場合です。たとえば、コンポーネントがネットワーク接続がアクティブかどうかを表示したいとします。ブラウザは、こ�?情報を navigator.onLine というプロパティを介して公開します。

こ�?値は React �?知らないところで変更される可能性がある�?で、useSyncExternalStore でそれを読み取るべきです。

import { useSyncExternalStore } from 'react';

function ChatIndicator() {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot);
  // ...
}

getSnapshot 関数を�?�装するためには、ブラウザ API から現在�?値を読み取ることが必要です：

function getSnapshot() {
  return navigator.onLine;
}

次に、subscribe 関数を�?�装する必要があります。例えば、navigator.onLine が変化すると、ブラウザは window オブジェクト上で online および offline というイベントを発火します。これら対応するイベントに callback 引数を登録し、それを解除する関数を返す必要があります：

function subscribe(callback) {
  window.addEventListener('online', callback);
  window.addEventListener('offline', callback);
  return () => {
    window.removeEventListener('online', callback);
    window.removeEventListener('offline', callback);
  };
}

これで React は、外部�? navigator.onLine API から値を読み取る方法と、そ�?変更にサブスクライブする方法を知ることができます。ネットワークからデバイスを切断すると、コンポーネントが反応して再レンダーされることに注�?してください：

ロジックをカスタムフックに抽出する

通常、useSyncExternalStore を直接コンポーネント内に記述することはありません。代わりに、自分自身�?カスタムフックから呼び出すことが一般的です。これにより、異なるコンポーネントから同じ外部ストアを使用できます。

例えば、こ�?カスタム useOnlineStatus フックはネットワークがオンラインであるかどうかを追跡します：

import { useSyncExternalStore } from 'react';

export function useOnlineStatus() {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot);
  return isOnline;
}

function getSnapshot() {
  // ...
}

function subscribe(callback) {
  // ...
}

これで、異なるコンポーネントが、基本的な�?�装を繰り返すことなく useOnlineStatus を呼び出せるようになりました：

サーバーレンダリング�?サポートを追加する

React アプリがサーバレンダリングを使用している場合、React コンポーネントは初期 HTML を生成するためにブラウザ環境外でも�?�行されます。これにより、外部ストアへ�?接続に関するいくつか�?課題が生じます。

• ブラウザ専用�? API に接続している場合、それはサーバ上では存在しないため動作しません。
• サードパーティ�?データストアに接続している場合、サーバとクライアント間でそ�?データを一致させる必要があります。

これら�?問題を解決するために、useSyncExternalStore に getServerSnapshot 関数を第 3 引数として渡します：

import { useSyncExternalStore } from 'react';

export function useOnlineStatus() {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
  return isOnline;
}

function getSnapshot() {
  return navigator.onLine;
}

function getServerSnapshot() {
  return true; // Always show "Online" for server-generated HTML
}

function subscribe(callback) {
  // ...
}

getServerSnapshot 関数は getSnapshot と似ていますが、以下�? 2 つ�?状況で�?み�?�行されます：

• サーバ上で、HTML を生成する際に�?�行される。
• クライアント上で、React がサーバ HTML をインタラクティブにするとき、つまりハイドレーション中に�?�行される。

これにより、アプリがインタラクティブになる前に使用される初期�?スナップショット値を指�?�できます。サーバレンダリング中に意味�?ある初期値が存在しない場合は、こ�?引数を省略して、強制的にクライアントでレンダーするようにします。

トラブルシューティング

“The result of getSnapshot should be cached” というエラーが出る

こ�?エラーは、getSnapshot 関数が呼ばれるたびに新しいオブジェクトを返していることを意味します。例えば：

function getSnapshot() {
  // 🔴 Do not return always different objects from getSnapshot
  return {
    todos: myStore.todos
  };
}

getSnapshot �?返り値が前回と異なる場合、React はコンポーネントを再レンダーします。こ�?ため、常に異なる値を返すと無限ループに入り、こ�?エラーが発生します。

getSnapshot オブジェクトは、�?�際に何かが変更された場合に�?み、別�?オブジェクトを返す必要があります。ストアにイミュータブルなデータが含まれている場合は、そ�?データを直接返すことができます：

function getSnapshot() {
  // ✅ You can return immutable data
  return myStore.todos;
}

ストアデータがミュータブルな場合、getSnapshot 関数はそ�?イミュータブルなスナップショットを返す必要があります。つまり、新しいオブジェクトを作成する必要はありますが、毎回作成してはいけないということです。そ�?代わりに、最後に計�?�されたスナップショットを保存しておき、ストア内�?データが変更されていない場合は前回と同じスナップショットを返すようにします。ミュータブルなデータが変更されたかどうかを判断する方法は、ミュータブルなストアによって異なります。

subscribe が毎レンダーごとに呼び出される

こ�? subscribe 関数はコンポーネント�?内部で�?�義されているため、再レンダーするたびに異なった値になります：

function ChatIndicator() {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot);
  
  // 🚩 Always a different function, so React will resubscribe on every re-render
  function subscribe() {
    // ...
  }

  // ...
}

React は、再レンダー間で異なる subscribe 関数を渡すと、ストアに再サブスクライブします。これがパフォーマンス�?問題を引き起こし、再サブスクライブを避けたい場合は、subscribe 関数を外部に移動してください：

function ChatIndicator() {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot);
  // ...
}

// ✅ Always the same function, so React won't need to resubscribe
function subscribe() {
  // ...
}

あるいは、subscribe を useCallback でラップすることで、引数が変更されたとき�?み再サブスクライブすることができます：

function ChatIndicator({ userId }) {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot);
  
  // ✅ Same function as long as userId doesn't change
  const subscribe = useCallback(() => {
    // ...
  }, [userId]);

  // ...
}