React の browser() API でブラウザ専用のコンポーネントを描画する

フォームの下書きを localStorage に保存しておき、ページを開き直したときに復元したい場面を考えてみましょう。ブラウザでのみ動くアプリなら、コンポーネントの初期化時に保存内容を安全に読み取れます。しかし、サーバーで HTML を生成する SSR（サーバーサイドレンダリング）を使っている場合、サーバーからユーザーのブラウザの localStorage を読むことはできないため、コンポーネントがサーバーで実行されているかブラウザで実行されているかを判定して、保存内容を読み取るタイミングを制御する必要があります。

従来は useEffect の中で保存内容を読み取り、state を更新して表示を切り替える方法が使われていました。これは useEffect がサーバーでは実行されず、ブラウザでマウントされた後に実行されることを利用した方法です。

function SavedDraft() {
  const [draft, setDraft] = useState(null);
 
  useEffect(() => {
    setDraft(localStorage.getItem("draft") ?? "");
  }, []);
 
  if (draft === null) return <p>下書きを読み込み中...</p>;
  return <p>保存した下書き: {draft}</p>;
}

しかし、useEffect を使う方法では、初回表示を一致させるために読み取り前の状態を表す null の state を用意したり、Effect から追加の再描画を起こしたりする必要がありました。また、待機中の表示もコンポーネントで管理するという課題がありました。

React DOM の新しい browser() API は、コンポーネントの描画をブラウザに任せるための API です。use(browser()) と書くと、そのコンポーネントのサーバーでの描画を止め、待機中の表示を <Suspense> に任せられます。

この記事では browser() の基本的な使い方について紹介します。

従来は useEffect で localStorage を読み取っていた

まず、SSR を使うときに localStorage の読み取りが問題になる理由を確認しましょう。次のコードでは、useState の初期値を決める関数の中で保存内容を読み取っています。

import { useState } from "react";
 
function SavedDraft() {
  const [draft] = useState(() => localStorage.getItem("draft") ?? "");
 
  return <p>保存した下書き: {draft}</p>;
}

このとき問題になるのは、このコンポーネントがサーバーとブラウザの両方で実行される可能性があることです。上記のコードは localStorage を提供していないサーバー環境で参照エラーになります。仮にサーバー環境に同名の API があっても、そこにユーザーのブラウザの保存内容があるわけではないため、ブラウザでの初回描画とサーバーでの初回描画が一致しないハイドレーションの不一致が起こります。

初回表示をそろえてから保存内容を読み取る

SSR には、サーバーで作った HTML をブラウザ側の React に引き継ぐ「ハイドレーション」という処理があります。React は既存の HTML にイベント処理などを接続するため、サーバーとブラウザで初回の描画結果が一致している必要があります。hydrateRoot の公式ドキュメントでも、不一致は修正すべきバグとして扱われています。

この条件を満たすため、まずは共通の表示を出し、ハイドレーション後に保存内容を読み取る方法が使われます。

import { useEffect, useState } from "react";
 
function SavedDraft() {
  // null は読み取り前、空文字列は保存内容がない状態
  const [draft, setDraft] = useState(null);
 
  useEffect(() => {
    setDraft(localStorage.getItem("draft") ?? "");
  }, []);
 
  if (draft === null) {
    return <p>下書きを読み込み中...</p>;
  }
 
  return <p>保存した下書き: {draft}</p>;
}

useEffect はサーバーでは実行されません。そのため、次の順序で表示が切り替わります。

1. サーバーでは draft が null のままなので「下書きを読み込み中...」を出力する。
2. ブラウザの初回描画でも draft は null なので、サーバーと同じ表示になる。
3. ハイドレーション後に Effect が実行され、localStorage の保存内容で state を更新する。
4. 更新された state を使って再描画し、保存内容を表示する。

React の公式ドキュメントでも、サーバーとクライアントで異なる内容を表示する方法として、Effect でマウント済みの状態へ切り替えるパターンが紹介されています。

従来の方法の課題

この実装は初回表示を一致させる有効な方法ですが、ブラウザ専用の内容を表示するために、いくつかの処理を自分で管理する必要がありました。

• 読み取り前の状態を表す必要がある: この例では null を使い、保存データがない状態の "" と区別している。
• Effect が追加の再描画を起こす: ブラウザで最初の表示を確定した後、保存内容を読むために Effect を実行し、state の更新で表示を切り替えるため、 本来不要な 2 回目の描画が発生する。
• 待機中の表示もコンポーネントで管理する: 保存内容を表示する処理に加えて、読み取り前に返す JSX とその分岐が必要

共通の Hook やラッパーへ切り出せば重複は減らせるものの、マウントを待ち、状態を更新して描画し直すという課題は残ります。

また、サーバーでの参照エラーを避けようとして、次のように typeof window だけで分岐する場合にも注意が必要です。typeof window による分岐はサーバー側には window オブジェクトが無いことを利用した参照エラーの回避策として従来はよく使われていました。

import { useState } from "react";
 
function SavedDraft() {
  const [draft] = useState(() =>
    typeof window === "undefined"
      ? ""
      : localStorage.getItem("draft") ?? "",
  );
 
  return <p>保存した下書き: {draft}</p>;
}

サーバーでは空文字列、ブラウザでは保存された文章になると、初回描画が一致しません。typeof window による分岐は、サーバーでの参照エラーを防いでも、ハイドレーションの不一致まで防ぐものではないのです。React はこの分岐を不一致のよくある原因として挙げています。

browser() API の基本的な使い方

browser() は react-dom からインポートします。戻り値を React の use() に渡すことで、その場所から先の描画をブラウザに任せます。use() は、Promise やコンテキストなどのリソースをレンダリング中に読み取る API です。

import { Suspense, use } from "react";
import { browser } from "react-dom";
 
function BrowserOnly() {
  use(browser());
 
  return <p>この内容はブラウザで描画されます。</p>;
}
 
export default function App() {
  return (
    <Suspense fallback={<p>読み込み中...</p>}>
      <BrowserOnly />
    </Suspense>
  );
}

<Suspense> は、子の描画が中断されたときに、代わりに fallback を表示するコンポーネントです。use(browser()) をサーバーで処理すると、React は最も近い親の Suspense 境界に fallback を残します。ブラウザで処理すると undefined が返るため、<Suspense> にキャッチされずに描画が行われるという仕組みです。

なぜ useBrowser() という Hook ではないのか

2026 年 7 月の導入 PRでは、通常の Hook とする代替案も検討されています。しかし Hook では呼び出し順序を守る必要があり、条件付きで呼べません。use() はコンポーネントや Hook の中で条件付きでも呼べるため、props に応じて SSR を続けるか判断できます。

例えば、サーバーに下書きがあればそのデータを、なければブラウザの localStorage から復元するケースです。以下のコードでは、initialDraft が渡されなかった場合だけ use(browser()) を呼び出します。

import { Suspense, use, useState } from "react";
import { browser } from "react-dom";
 
// initialDraft はサーバーで DB などから取得する想定
function DraftEditor({ initialDraft }) {
  if (initialDraft === undefined) {
    use(browser("初期データがないため localStorage から復元します。"));
  }
 
  const [draft, setDraft] = useState(() =>
    initialDraft !== undefined
      ? initialDraft
      : localStorage.getItem("draft") ?? "",
  );
 
  return (
    <label>
      下書き
      <textarea
        value={draft}
        onChange={(event) => setDraft(event.target.value)}
      />
    </label>
  );
}

また use() を使わずに単に browser() 自体が例外を投げる案についても、任意の場所から呼べてしまい、途中の catch によって意図せず処理が妨げられる懸念が説明されています。

このように、browser() と use() を組み合わせる形には、条件付きの利用を許しつつ、レンダリングに関わる場所で使うという意図があります。

localStorage を使うコンポーネントを描画する

それでは冒頭にあげた下書きを編集し、再読み込み後に復元できる入力欄を実装しましょう。ここでは JSX を利用できる React の SSR 環境を前提とします。検証に使用した React と React DOM のバージョンは以下のとおりです。

npm install --save-exact [email protected] [email protected]

以下のコードでは、useState で保存内容を読み取る前に use(browser()) を呼びます。browser() の第 1 引数にはコンテンツをブラウザでレンダリングする必要がある理由を説明する文字列または関数を渡せます。

import { Suspense, use, useState } from "react";
import { browser } from "react-dom";
 
export function SavedDraft() {
  use(browser("下書きは localStorage に保存されています。"));
  const [draft, setDraft] = useState(
    () => localStorage.getItem("draft") ?? "",
  );
 
  function handleChange(event) {
    const nextDraft = event.target.value;
    setDraft(nextDraft);
    localStorage.setItem("draft", nextDraft);
  }
 
  return (
    <label>
      下書き
      <textarea value={draft} onChange={handleChange} rows={4} />
    </label>
  );
}
 
export default function App() {
  return (
    <main>
      <h1>下書きメモ</h1>
      <Suspense fallback={<p>下書きを読み込み中...</p>}>
        <SavedDraft />
      </Suspense>
    </main>
  );
}

サーバーでは use(browser(...)) で描画が止まるため、後続の localStorage.getItem() は実行されません。<Suspense> の fallback のコンテンツが表示されます。

ブラウザではその先へ進み、localStorage の値を state の初期値として使います。従来の例にあった読み取り前の null と Effect による state 更新が不要になりました。またフォールバックの表示も <Suspense> に任せられるようになっているため、表示の出し分けという責務が呼び出し側に移るという React の思想に沿った形になっています。

onBrowserBailout で描画の切り替えを観測する

SSR を避ける従来の手法には、サーバーで意図的に例外を投げ、Suspense の fallback を返してブラウザで描画し直す方法もありました。

import { Suspense, useState } from "react";
 
function SavedDraft() {
  if (typeof window === "undefined") {
    throw new Error("下書きはブラウザでのみ描画します。");
  }
 
  const [draft] = useState(
    () => localStorage.getItem("draft") ?? "",
  );
 
  return <p>保存した下書き: {draft}</p>;
}
 
export default function App() {
  return (
    <main>
      <h1>下書きメモ</h1>
      <Suspense fallback={<p>下書きを読み込み中...</p>}>
        <SavedDraft />
      </Suspense>
    </main>
  );
}

しかしこの手法には、意図的な中断でも通常のエラーとして報告されるという課題があります。

use(browser()) による描画の中断では、React が識別できる形で表すため通常のエラーと区別されます。サーバーレンダラーの onError や、ブラウザ側の hydrateRoot の onRecoverableError は呼ばれません。代わりに、サーバー側で onBrowserBailout を指定すると、ブラウザでのみ描画するために中断したことを捕捉できます。

import { renderToPipeableStream } from "react-dom/server";
import App from "./App.jsx";
 
export function renderApp(response) {
  const { pipe } = renderToPipeableStream(<App />, {
    onShellReady() {
      response.setHeader("Content-Type", "text/html; charset=utf-8");
      pipe(response);
    },
    // ブラウザでのみ描画するために中断したときの通知
    onBrowserBailout(error, errorInfo) {
      // error.cause には `browser()` の第 1 引数の文字列または関数の戻り値が入る
      console.log(error.cause);
      console.log(errorInfo.componentStack);
    },
  });
}

onShellReady は最初に送れる HTML の準備ができたときの通知です。onBrowserBailout には、理由を cause に持つ Error と、発生箇所のコンポーネントスタックが渡されます。先ほどのサンプルでは「下書きは localStorage に保存されています。」と、SavedDraft を含むスタックを受け取れました。

下書きは localStorage に保存されています。
 
    at SavedDraft (/dist/App.js:6:3)
    at Suspense (<anonymous>)
    at main (<anonymous>)
    at App (<anonymous>)
    at div (<anonymous>)
    at body (<anonymous>)
    at html (<anonymous>)

まとめ

• 従来の Effect を使う方法では、SSR とブラウザの初回表示をそろえてから保存内容を読み取り、state の更新で再描画する必要があった
• typeof window の分岐だけでは、サーバーとブラウザの初回描画が異なる場合のハイドレーション不一致を防げない
• use(browser()) はサーバーでの描画を中断し、最も近い Suspense 境界に fallback を残す。ブラウザでは後続のコードを実行する
• 意図した描画の切り替えは onBrowserBailout で捕捉できる

参考

• browser – React
• use – React
• useEffect: Displaying different content on the server and the client – React
• hydrateRoot – React
• Add ReactDOM browser() API #37143
• Add onBrowserBailout Fizz option #37193