Hono를 사용한 Cloudflare Workers의 React

Hono는 Cloudflare Workers, Deno Deploy, Bun, Node.js를 비롯한 엣지 런타임에서 실행되도록 설계된 가볍고 매우 빠른 웹 프레임워크입니다. API는 Express에서 영감을 받았지만 웹 표준(Fetch API, Request/Response)을 기반으로 처음부터 구축되었으므로 엣지 환경에 자연스럽게 어울립니다.

Cloudflare Workers용 새 Hono 프로젝트의 기본 구조를 만드는 방법은 간단합니다. npm create hono@latest를 실행하면 템플릿을 선택하라는 메시지가 표시됩니다. 여기서 "cloudflare-workers"를 선택하면 wrangler(Cloudflare의 CLI)와 Hono 의존성이 미리 설정된 프로젝트가 생성됩니다.

Hono Worker 안에서 React를 서버 렌더링하려면 react, react-dom, @types/react를 설치한 다음 react-dom/server에서 renderToReadableStream을 가져오십시오. 이 함수는 React 18의 스트리밍 API에 포함되어 있으며, Web Streams API를 지원하는 환경을 위해 설계되었습니다. Cloudflare Workers가 바로 이러한 환경입니다.

일반적인 SSR 라우트 처리기는 루트 React 컴포넌트와 함께 renderToReadableStream을 호출하고 스트림을 기다린 다음, c.body(stream, { headers: { 'Content-Type': 'text/html' } }) 또는 c.html(htmlString)을 사용하여 응답을 보냅니다. 스트림은 HTML 조각을 생성하므로 브라우저가 이를 점진적으로 렌더링할 수 있습니다.

renderToReadableStream은 HTML 조각으로 이루어진 ReadableStream으로 해석되는 프라미스를 반환합니다. 이 ReadableStream은 Web Streams API를 따르며 Response 객체의 본문으로 직접 전달할 수 있으므로 Cloudflare Workers의 fetch 처리기에 매우 잘 맞습니다.

React 스트림은 컴포넌트 트리의 HTML을 생성하지만 주변 문서는 생성하지 않습니다. 따라서 스트림을 HTML 셸에 삽입해야 합니다. HTML 셸은 문서 형식 선언, 메타 태그와 CSS 링크가 포함된 head, 여는 body 태그, React 스트림, 그리고 닫는 body 및 html 태그로 이루어진 문자열입니다.

Vite로 빌드한 React 클라이언트 번들은 Worker와 함께 제공해야 합니다. Cloudflare Pages 또는 Workers Assets 기능이 이 작업을 처리합니다. c.env.ASSETS.fetch(request)는 에셋 요청(JS, CSS, 이미지)을 Worker 배포와 함께 업로드된 정적 파일로 라우팅합니다.

Worker 진입 파일은 fetch 처리기를 포함한 기본 객체를 내보냅니다. export default { fetch: app.fetch }. Hono의 app.fetch 메서드는 Request를 받고 Response를 반환하는 호환 가능한 fetch 처리기이므로 Workers 런타임에 직접 연결할 수 있습니다.

wrangler dev는 컴퓨터에서 Cloudflare Workers 런타임을 모방하는 로컬 개발 서버를 시작합니다. 파일 변경을 감지하여 자동으로 다시 불러오므로, 실제 운영 환경에 배포하기 전에 빠른 로컬 개발 주기를 유지할 수 있습니다.

wrangler deploy는 Worker 코드를 묶어 Cloudflare 네트워크에 업로드하며, 몇 초 안에 300곳이 넘는 모든 엣지 위치에서 서비스를 시작하게 합니다. wrangler.toml 구성 파일에는 계정 ID, Worker 이름, 그리고 KV 네임스페이스나 D1 데이터베이스 바인딩이 지정됩니다.

클라이언트 측 상호작용을 지원하려면 renderToReadableStream에 bootstrapScripts: ['/assets/client.js']를 전달하십시오. React는 HTML에 스크립트 태그를 삽입하여 클라이언트 번들을 로드하고 서버에서 렌더링된 DOM에서 hydrateRoot를 호출하게 하므로, JS가 로드된 후 페이지가 상호작용 가능해집니다.

renderToReadableStream은 무엇을 반환하나요?

Hono는 React의 renderToReadableStream과 깔끔하게 통합되는 가벼운 엣지 네이티브 HTTP 프레임워크를 제공합니다. Worker 진입점은 app.fetch를 Workers 런타임으로 직접 내보내고, 정적 에셋은 ASSETS 바인딩을 통해 제공되며, wrangler는 로컬 개발과 실제 운영 환경 배포를 모두 처리합니다. bootstrapScripts는 스트리밍된 HTML을 클라이언트 측 하이드레이션 번들과 연결합니다.