prerender

const {prelude, postponed} = await prerender(reactNode, options?)

• Справочник
  • prerender(reactNode, options?)
• Использование
  • Преобразование дерева React в поток статического HTML
  • Преобразование дерева React в строку статического HTML
  • Ожидание загрузки всех данных
  • Прерывание предварительного рендеринга
• Устранение неполадок
  • Поток не начинается, пока не отрендерится всё приложение

Справочник

prerender(reactNode, options?)

Вызовите prerender, чтобы преобразовать приложение в статический HTML.

import { prerender } from 'react-dom/static';

async function handler(request, response) {
  const {prelude} = await prerender(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(prelude, {
    headers: { 'content-type': 'text/html' },
  });
}

На клиенте вызовите hydrateRoot, чтобы сделать HTML, сгенерированный на сервере, интерактивным.

См. дополнительные примеры ниже.

Параметры

• reactNode: узел React, который нужно преобразовать в HTML. Например, JSX-узел вроде <App />. Предполагается, что он представляет весь документ, поэтому компонент App должен отрисовывать тег <html>.

• необязательный options: объект с параметрами статической генерации.

  • необязательный bootstrapScriptContent: если указан, эта строка будет помещена во встроенный тег <script>.
  • необязательный bootstrapScripts: массив строк с URL тегов <script>, которые нужно добавить на страницу. Используйте его, чтобы включить <script>, вызывающий hydrateRoot. Не указывайте его, если React вообще не должен запускаться на клиенте.
  • необязательный bootstrapModules: аналог bootstrapScripts, но вместо него добавляет <script type="module">.
  • необязательный identifierPrefix: строковый префикс, который React использует для идентификаторов, создаваемых с помощью useId. Полезен для предотвращения конфликтов при использовании нескольких корней на одной странице. Должен совпадать с префиксом, переданным в hydrateRoot.
  • необязательный namespaceURI: строка с URI пространства имён корня для потока. По умолчанию используется обычный HTML. Передайте 'http://www.w3.org/2000/svg' для SVG или 'http://www.w3.org/1998/Math/MathML' для MathML.
  • необязательный onError: функция обратного вызова, вызываемая при любой серверной ошибке — восстановимой или нет. По умолчанию она только вызывает console.error. Если вы переопределите её для ведения журнала аварийных ошибок, обязательно продолжайте вызывать console.error. Её также можно использовать, чтобы изменить код состояния до отправки оболочки.
  • необязательный progressiveChunkSize: количество байтов в одном фрагменте. Подробнее о стандартной эвристике.
  • необязательный signal: сигнал прерывания, который позволяет прервать предварительный рендеринг и отрисовать оставшуюся часть на клиенте.

Возвращаемое значение

prerender возвращает Promise:

• Если рендеринг выполнен успешно, Promise будет разрешён объектом, содержащим:
  • prelude: поток Web Streams с HTML. Этот поток можно использовать для отправки ответа фрагментами либо прочитать его целиком в строку.
  • postponed: сериализуемый в JSON непрозрачный объект, который можно передать в resume, если prerender не завершился. В противном случае — null, означающий, что prelude содержит всё содержимое и продолжение не требуется.
• Если рендеринг завершится ошибкой, Promise будет отклонён. Используйте это, чтобы вывести резервную оболочку.

Ограничения

nonce нельзя использовать как параметр при предварительном рендеринге. Значения nonce должны быть уникальными для каждого запроса. Если вы используете nonce для защиты приложения с помощью CSP, включать значение nonce в результат предварительного рендеринга было бы неправильно и небезопасно.

Использование

Преобразование дерева React в поток статического HTML

Вызовите prerender, чтобы преобразовать дерево React в статический HTML, записав результат в поток Web ReadableStream::

import { prerender } from 'react-dom/static';

async function handler(request) {
  const {prelude} = await prerender(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(prelude, {
    headers: { 'content-type': 'text/html' },
  });
}

Помимо корневого компонента, необходимо передать список путей к bootstrap-скриптам <script>. Корневой компонент должен возвращать весь документ, включая корневой тег <html>.

Например, это может выглядеть так:

export default function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" href="/styles.css"></link>
        <title>My app</title>
      </head>
      <body>
        <Router />
      </body>
    </html>
  );
}

React добавит doctype и теги bootstrap-скриптов <script> в результирующий HTML-поток:

<!DOCTYPE html>
<html>
  <!-- ... HTML from your components ... -->
</html>
<script src="/main.js" async=""></script>

На клиенте bootstrap-скрипт должен гидратировать весь document вызовом hydrateRoot:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App />);

Это добавит обработчики событий к статическому HTML, сгенерированному на сервере, и сделает его интерактивным.

export default function App({ assetMap }) {
  return (
    <html>
      <head>
        <title>My app</title>
        <link rel="stylesheet" href={assetMap['styles.css']}></link>
      </head>
      ...
    </html>
  );
}

// You'd need to get this JSON from your build tooling, e.g. read it from the build output.
const assetMap = {
  'styles.css': '/styles.123456.css',
  'main.js': '/main.123456.js'
};

async function handler(request) {
  const {prelude} = await prerender(<App assetMap={assetMap} />, {
    bootstrapScripts: [assetMap['/main.js']]
  });
  return new Response(prelude, {
    headers: { 'content-type': 'text/html' },
  });
}

// You'd need to get this JSON from your build tooling.
const assetMap = {
  'styles.css': '/styles.123456.css',
  'main.js': '/main.123456.js'
};

async function handler(request) {
  const {prelude} = await prerender(<App assetMap={assetMap} />, {
    // Careful: It's safe to stringify() this because this data isn't user-generated.
    bootstrapScriptContent: `window.assetMap = ${JSON.stringify(assetMap)};`,
    bootstrapScripts: [assetMap['/main.js']],
  });
  return new Response(prelude, {
    headers: { 'content-type': 'text/html' },
  });
}

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App assetMap={window.assetMap} />);

Преобразование дерева React в строку статического HTML

Вызовите prerender, чтобы преобразовать приложение в строку статического HTML:

import { prerender } from 'react-dom/static';

async function renderToString() {
  const {prelude} = await prerender(<App />, {
    bootstrapScripts: ['/main.js']
  });

  const reader = prelude.getReader();
  let content = '';
  while (true) {
    const {done, value} = await reader.read();
    if (done) {
      return content;
    }
    content += Buffer.from(value).toString('utf8');
  }
}

В результате будет создан исходный неинтерактивный HTML-код компонентов React. На клиенте необходимо вызвать hydrateRoot, чтобы гидратировать этот HTML, сгенерированный на сервере, и сделать его интерактивным.

Ожидание загрузки всех данных

prerender дожидается загрузки всех данных, прежде чем завершить генерацию статического HTML и разрешиться. Например, представьте страницу профиля, на которой отображаются обложка, боковая панель с друзьями и фотографиями, а также список публикаций:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Sidebar>
        <Friends />
        <Photos />
      </Sidebar>
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

Представим, что для <Posts /> необходимо загрузить данные, и это занимает некоторое время. В идеале нужно дождаться загрузки публикаций, чтобы включить их в HTML. Для этого можно использовать Suspense, чтобы приостановить выполнение до получения данных; prerender дождётся завершения загрузки приостановленного содержимого, прежде чем вернуть статический HTML.

Прерывание предварительного рендеринга

Можно принудительно остановить предварительный рендеринг по истечении заданного времени ожидания:

async function renderToString() {
  const controller = new AbortController();
  setTimeout(() => {
    controller.abort()
  }, 10000);

  try {
    // the prelude will contain all the HTML that was prerendered
    // before the controller aborted.
    const {prelude} = await prerender(<App />, {
      signal: controller.signal,
    });
    //...

Границы Suspense с незавершёнными дочерними элементами будут включены в прелюдию в резервном состоянии.

Это можно использовать для частичного предварительного рендеринга вместе с resume или resumeAndPrerender.

Устранение неполадок

Поток не начинается, пока не отрендерится всё приложение

Ответ prerender ожидает завершения рендеринга всего приложения, включая разрешение всех границ Suspense. Этот API предназначен для предварительной генерации статических сайтов (SSG) и не поддерживает передачу дополнительного содержимого по мере его загрузки.

Чтобы передавать содержимое по мере его загрузки, используйте потоковый API серверного рендеринга, например renderToReadableStream.