React na Cloudflare Workers z Hono

Hono to lekki, niezwykle szybki framework internetowy zaprojektowany do działania w środowiskach uruchomieniowych edge, takich jak Cloudflare Workers, Deno Deploy, Bun i Node.js. Jego API jest inspirowane Expressem, ale zostało od podstaw zbudowane zgodnie ze standardami Web (Fetch API, Request/Response), dzięki czemu naturalnie pasuje do środowisk edge.

Utworzenie szkieletu nowego projektu Hono dla Cloudflare Workers jest proste: npm create hono@latest prosi o wybranie szablonu, wybranie "cloudflare-workers" i tworzy projekt wstępnie skonfigurowany z wranglerem (interfejsem CLI Cloudflare) oraz zależnością Hono.

Aby renderować React po stronie serwera wewnątrz Hono Worker, należy zainstalować react, react-dom i @types/react, a następnie zaimportować renderToReadableStream z react-dom/server. Ta funkcja jest częścią interfejsu strumieniowego React 18 i została zaprojektowana dla środowisk obsługujących Web Streams API — a Cloudflare Workers takie środowiska zapewniają.

Typowa procedura obsługi trasy SSR wywołuje renderToReadableStream z głównym komponentem Reacta, czeka na strumień, a następnie używa c.body(stream, { headers: { 'Content-Type': 'text/html' } }) lub c.html(htmlString), aby wysłać odpowiedź. Strumień generuje fragmenty kodu HTML, które przeglądarka może renderować stopniowo.

renderToReadableStream zwraca obiekt Promise, który rozwiązuje się do obiektu ReadableStream zawierającego fragmenty kodu HTML. ReadableStream jest zgodny z Web Streams API i można go przekazać bezpośrednio jako treść obiektu Response, dzięki czemu idealnie pasuje do procedury obsługi fetch w Cloudflare Workers.

Strumień Reacta generuje kod HTML drzewa komponentów, ale nie otaczający go dokument. Należy wstrzyknąć strumień do powłoki HTML: ciągu zawierającego doctype, element head z metadanymi i odwołaniem do CSS, otwierający znacznik body — następnie strumień Reacta — a na końcu zamykające znaczniki body i html.

Pakiet klienta Reacta zbudowany za pomocą Vite musi być udostępniany razem z Workerem. Obsługują to Cloudflare Pages lub funkcja Workers Assets: c.env.ASSETS.fetch(request) kieruje żądania zasobów (JS, CSS, obrazów) do plików statycznych przesłanych wraz z wdrożeniem Workera.

Plik wejściowy Workera eksportuje domyślny obiekt z procedurą obsługi fetch: export default { fetch: app.fetch }. Metoda app.fetch Hono jest już zgodną procedurą obsługi fetch, która otrzymuje obiekt Request i zwraca obiekt Response, więc można ją bezpośrednio podłączyć do środowiska uruchomieniowego Workers.

wrangler dev uruchamia na komputerze lokalny serwer deweloperski emulujący środowisko uruchomieniowe Cloudflare Workers. Obserwuje zmiany w plikach i automatycznie przeładowuje aplikację, zapewniając szybki cykl lokalnego programowania przed wdrożeniem na produkcję.

wrangler deploy pakuje i przesyła kod Workera do sieci Cloudflare, udostępniając go we wszystkich ponad 300 lokalizacjach edge w ciągu kilku sekund. Plik konfiguracyjny wrangler.toml określa identyfikator konta, nazwę Workera oraz powiązania z przestrzeniami nazw KV lub bazami danych D1.

W przypadku interaktywności po stronie klienta należy przekazać bootstrapScripts: ['/assets/client.js'] do renderToReadableStream. React wstrzyknie do kodu HTML znacznik script, który załaduje pakiet klienta i wywoła hydrateRoot na DOM wyrenderowanym po stronie serwera, nadając stronie interaktywność po załadowaniu JavaScriptu.

Co zwraca renderToReadableStream?

Hono zapewnia lekki, natywny dla edge framework HTTP, który dobrze integruje się z renderToReadableStream Reacta. Punkt wejścia Workera eksportuje bezpośrednio app.fetch do środowiska uruchomieniowego Workers, zasoby statyczne są udostępniane za pośrednictwem powiązań ASSETS, a wrangler obsługuje zarówno programowanie lokalne, jak i wdrażanie produkcyjne. bootstrapScripts łączy strumieniowany kod HTML z pakietem hydratacji po stronie klienta.