React на Cloudflare Workers с Hono

Hono — лёгкий и сверхбыстрый веб-фреймворк, предназначенный для работы в периферийных средах выполнения, включая Cloudflare Workers, Deno Deploy, Bun и Node.js. Его API вдохновлён Express, но создан с нуля на основе веб-стандартов (Fetch API, Request/Response), поэтому он естественно подходит для периферийных сред.

Создать каркас нового проекта Hono для Cloudflare Workers несложно: команда npm create hono@latest предлагает выбрать шаблон, указать "cloudflare-workers" и создаёт проект с предварительно настроенными wrangler, CLI Cloudflare, и зависимостью Hono.

Чтобы выполнять серверный рендеринг React внутри Worker Hono, установите react, react-dom и @types/react, а затем импортируйте renderToReadableStream из react-dom/server. Эта функция является частью потокового API React 18 и предназначена для сред, поддерживающих API веб-потоков, — Cloudflare Workers поддерживает такой API.

Типичный обработчик маршрута SSR вызывает renderToReadableStream с корневым компонентом React, ожидает получения потока, а затем использует c.body(stream, { headers: { 'Content-Type': 'text/html' } }) или c.html(htmlString), чтобы отправить ответ. Поток создаёт фрагменты HTML, которые браузер может постепенно отображать.

renderToReadableStream возвращает Promise, разрешающийся в ReadableStream с фрагментами HTML. Этот ReadableStream соответствует API веб-потоков и может быть напрямую передан как тело объекта Response, что идеально подходит для обработчика fetch в Cloudflare Workers.

Поток React создаёт HTML-дерево компонентов, но не окружающий документ. Необходимо встроить поток в HTML-оболочку: строку, содержащую объявление типа документа, элемент head с метатегами и ссылкой на CSS, открывающий тег body, затем поток React, а после него закрывающие теги body и html.

Клиентский пакет React, созданный с помощью Vite, необходимо предоставлять вместе с Worker. Для этого можно использовать Cloudflare Pages или функцию Assets в Workers: c.env.ASSETS.fetch(request) направляет запросы ресурсов (JS, CSS, изображений) к статическим файлам, загруженным при развёртывании Worker.

Файл Worker, являющийся точкой входа, экспортирует объект по умолчанию с обработчиком fetch: export default { fetch: app.fetch }. Метод app.fetch Hono уже является совместимым обработчиком fetch: он получает Request и возвращает Response, поэтому напрямую подключается к среде выполнения Workers.

wrangler dev запускает локальный сервер разработки, эмулирующий среду выполнения Cloudflare Workers на Вашем компьютере. Он отслеживает изменения файлов и автоматически перезагружает приложение, обеспечивая быстрый цикл локальной разработки перед развёртыванием в рабочей среде.

wrangler deploy собирает и загружает код Worker в сеть Cloudflare, делая его доступным во всех более чем 300 периферийных местоположениях за несколько секунд. Файл конфигурации wrangler.toml задаёт ID аккаунта, имя Worker, а также привязки любого пространства имён KV или базы данных D1.

Для интерактивности на стороне клиента передайте bootstrapScripts: ['/assets/client.js'] в renderToReadableStream. React добавит в HTML тег script, который загружает клиентский пакет и вызывает hydrateRoot для DOM, отрендеренного на сервере, делая страницу интерактивной после загрузки JS.

Что возвращает renderToReadableStream?

Hono предоставляет лёгкий HTTP-фреймворк, изначально предназначенный для периферийных сред, который хорошо интегрируется с renderToReadableStream React. Точка входа Worker напрямую экспортирует app.fetch в среду выполнения Workers, статические ресурсы предоставляются через привязки ASSETS, а wrangler отвечает и за локальную разработку, и за развёртывание в рабочей среде. bootstrapScripts связывает потоковый HTML с пакетом гидратации на стороне клиента.