ReactDOMServer

この記事は古くなっており、今後更新されません。新しい React 日本語ドキュメントである ja.react.dev をご利用ください。

以下の新しいドキュメントで最新の React の使い方が学べます。

react-dom: サーバ用 API

ReactDOMServer オブジェクトはコンポーネントを静的なマークアップとして変換できるようにします。これは、一般的に Node サーバで使われます。

// ES modules
import * as ReactDOMServer from 'react-dom/server';
// CommonJS
var ReactDOMServer = require('react-dom/server');

概要

以下のメソッドは Node.js の Stream 環境でのみ動作します：

renderToPipeableStream()
renderToNodeStream()（非推奨）
renderToStaticNodeStream()

以下のメソッドは Web Stream の環境（ブラウザ、Deno やいくつかのモダンなエッジランタイム）でのみ動作します：

renderToReadableStream()

以下のメソッドはストリームをサポートしない環境でも動作します：

renderToString()
renderToStaticMarkup()

リファレンス

`renderToPipeableStream()`

This content is out of date.

Read the new React documentation for renderToPipeableStream.

ReactDOMServer.renderToPipeableStream(element, options)

React 要素を初期状態の HTML に変換します。出力をパイプするための pipe(res) メソッドとリクエストを中止するための abort() メソッドを持ったストリームを返します。サスペンスや、HTML をストリーミングして「遅れてやってくる」コンテンツのブロックをインライン <script> タグで埋めるための機能を完全にサポートしています。詳細はこちら。

このようにサーバでレンダーされたマークアップを有するノードに対して ReactDOM.hydrateRoot() をコールすると、React はマークアップを保持してイベントハンドラだけをアタッチしますので、非常によい初回ロード体験が実現できます。

let didError = false;
const stream = renderToPipeableStream(
  <App />,
  {
    onShellReady() {
      // The content above all Suspense boundaries is ready.
      // If something errored before we started streaming, we set the error code appropriately.
      res.statusCode = didError ? 500 : 200;
      res.setHeader('Content-type', 'text/html');
      stream.pipe(res);
    },
    onShellError(error) {
      // Something errored before we could complete the shell so we emit an alternative shell.
      res.statusCode = 500;
      res.send(
        '<!doctype html><p>Loading...</p><script src="clientrender.js"></script>'
      );
    },
    onAllReady() {
      // If you don't want streaming, use this instead of onShellReady.
      // This will fire after the entire page content is ready.
      // You can use this for crawlers or static generation.

      // res.statusCode = didError ? 500 : 200;
      // res.setHeader('Content-type', 'text/html');
      // stream.pipe(res);
    },
    onError(err) {
      didError = true;
      console.error(err);
    },
  }
);

オプションの全リストを参照。

補足：

これは Node.js 専用の API です。Deno やモダンなエッジランタイムのような Web Stream の環境では、代わりに renderToReadableStream を使用してください。

`renderToReadableStream()`

This content is out of date.

Read the new React documentation for renderToReadableStream.

ReactDOMServer.renderToReadableStream(element, options);

React 要素を初期状態の HTML にストリーミングします。Readable Stream として resolve する Promise を返します。サスペンスと HTML ストリーミングを完全にサポートします。詳細はこちら。

let controller = new AbortController();
let didError = false;
try {
  let stream = await renderToReadableStream(
    <html>
      <body>Success</body>
    </html>,
    {
      signal: controller.signal,
      onError(error) {
        didError = true;
        console.error(error);
      }
    }
  );
  
  // This is to wait for all Suspense boundaries to be ready. You can uncomment
  // this line if you want to buffer the entire HTML instead of streaming it.
  // You can use this for crawlers or static generation:

  // await stream.allReady;

  return new Response(stream, {
    status: didError ? 500 : 200,
    headers: {'Content-Type': 'text/html'},
  });
} catch (error) {
  return new Response(
    '<!doctype html><p>Loading...</p><script src="clientrender.js"></script>',
    {
      status: 500,
      headers: {'Content-Type': 'text/html'},
    }
  );
}

オプションの全リストを参照。

補足：

この API は Web Streams に依存しています。Node.js では代わりに renderToPipeableStream を使用してください。

`renderToNodeStream()`（非推奨）

This content is out of date.

Read the new React documentation for renderToNodeStream.

ReactDOMServer.renderToNodeStream(element)

React 要素を初期状態の HTML にストリーミングします。HTML 文字列を出力する Node.js の読み取りストリームを返します。このストリームからの HTML 出力は ReactDOMServer.renderToString が返すものと全く同じです。このメソッドを使ってサーバで HTML を生成し、初回リクエスト時にマークアップを送信することで、ページロードを高速化し、SEO 目的でサーチエンジンがクロールできるようになります。

補足：

この API はサーバ専用です。ブラウザでは利用できません。

このメソッドが返すストリームは UTF-8 でエンコードされたバイトストリームを返します。別の方式でエンコードされたストリームが必要な場合、テキストのトランスコーディングのために変換ストリームを提供している iconv-lite のようなプロジェクトを参照してください。

`renderToStaticNodeStream()`

This content is out of date.

Read the new React documentation for renderToStaticNodeStream.

ReactDOMServer.renderToStaticNodeStream(element)

React が内部的に使用する data-reactroot のような追加の DOM 属性を作成しないことを除いて、renderToNodeStream と同様の動作をします。このメソッドは React を単純な静的サイトジェネレータとして使用したい場合に便利で、追加の属性を省略することでバイト数を削減できます。

このストリームによる HTML 出力は ReactDOMServer.renderToStaticMarkup が返すものと全く同じです。

マークアップをインタラクティブなものにするために、クライアントで React を導入しようとしている場合は、このメソッドを使用しないでください。代わりに、サーバで renderToNodeStream を、そしてクライアントで ReactDOM.hydrateRoot() を使用してください。

補足：

この API はサーバ専用です。ブラウザでは利用できません。

このメソッドが返すストリームは UTF-8 でエンコードされたバイトストリームを返します。別の方式でエンコードされたストリームが必要な場合、テキストのトランスコーディングのために変換ストリームを提供している iconv-lite のようなプロジェクトを参照してください。

`renderToString()`

This content is out of date.

Read the new React documentation for renderToString.

ReactDOMServer.renderToString(element)

React 要素を初期状態の HTML に変換します。React は HTML 文字列を返します。このメソッドを使ってサーバで HTML を生成し、初回リクエスト時にマークアップを送信することで、ページロードを高速化し、SEO 目的でサーチエンジンがクロールできるようになります。

補足

この API は Suspense を部分的にしかサポートしておらず、ストリーミングが行えません。

サーバサイドでは、renderToPipeableStream（Node.js の場合）または renderToReadableStream（Web Stream の場合）の利用をお勧めします。

`renderToStaticMarkup()`

This content is out of date.

Read the new React documentation for renderToStaticMarkup.

ReactDOMServer.renderToStaticMarkup(element)

React が内部的に使用する data-reactroot のような追加の DOM 属性を作成しないことを除いて、renderToString と同様の動作をします。このメソッドは React を単純な静的サイトジェネレータとして使用したい場合に便利で、追加の属性を省略することでバイト数を削減できます。

クライアントで React を使ってマークアップをインタラクティブにする目的では、このメソッドは使わないでください。代わりにサーバで renderToString、クライアントで ReactDOM.hydrateRoot() を使うようにします。

Is this page useful?このページを編集する

概要

リファレンス

renderToPipeableStream()

renderToReadableStream()

renderToNodeStream()（非推奨）

renderToStaticNodeStream()