From 8543e87ec05bb8d7ffe538e5c334a956481372d3 Mon Sep 17 00:00:00 2001 From: aynaash Date: Tue, 16 Jun 2026 01:59:05 +0300 Subject: [PATCH] docs(cloudflare): correct over-claim on client hydration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Next 15 .js manifest fix (#30) wires the client reference manifest that was previously null — a real, general bug. But I marked "client hydration resolved" before browser-validating, which was premature: the manifest is necessary plumbing, not a guarantee an app hydrates. In practice a browser "client-side exception" is usually the app's own client code — most often a NEXT_PUBLIC_* / auth env var missing at build time (inlined into the client bundle), so a provider throws on hydration. The deploy serves the HTML + chunks + RSC Flight payload correctly. Reframe the doc: manifest plumbing is wired; full hydration also depends on the app's client config. Add a troubleshooting note. Co-Authored-By: Claude Opus 4.8 --- CLOUDFLARE_PARITY.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/CLOUDFLARE_PARITY.md b/CLOUDFLARE_PARITY.md index b2906dd..52a5e77 100644 --- a/CLOUDFLARE_PARITY.md +++ b/CLOUDFLARE_PARITY.md @@ -5,18 +5,22 @@ compiles a Next.js standalone build into a single Worker bundle (`nextcompile`) and serves static assets from R2. This document is the source of truth for **what is production-ready and what is not**. -> TL;DR — The Cloudflare target is production-ready for **static + client-side** -> Next.js apps (marketing, docs, blogs, API routes, `"use client"` interactivity). -> It does **not** yet fully support apps that rely on **dynamic server-side -> rendering** of the React tree. For those, use the **VPS** or **AWS Lambda** -> target until the SSR runtime gap below is closed. +> TL;DR — The Cloudflare target serves static + prerendered pages (with their +> client chunks and RSC Flight payload) correctly. It does **not** yet support +> apps that rely on **dynamic server-side rendering** of the React tree; use the +> **VPS** or **AWS Lambda** target for those until the SSR runtime gap closes. +> +> Note: a "client-side exception" in the browser is usually the **app's own** +> client code, not the deploy — most often a `NEXT_PUBLIC_*` / auth env var that +> was missing at **build** time (those are inlined into the client bundle), so a +> provider throws on hydration. Check the browser console and the build log. ## ✅ Production-ready on Cloudflare | Capability | Notes | |---|---| | Static / prerendered pages (`○`, `●`) | Served from the Worker + R2 | -| Client-component hydration (`"use client"`) | Reference manifests wired for Next 14 (`.json`) **and** Next 15 (`.js`) — v0.14+ | +| Client reference manifests | Wired for Next 14 (`.json`) **and** Next 15 (`.js`) — v0.14+. (Manifest plumbing only; whether a given app *hydrates* also depends on its own client code + build-time env.) | | API routes (`ƒ /api/*`) | Dispatched by the Worker | | Middleware | Runs ahead of the dispatcher | | Static assets (`/_next/static`, `/public`) | Uploaded to R2, content-hash skipped | @@ -61,9 +65,11 @@ full RSC streaming as unsupported on the Cloudflare target for now. ## Status of the gaps -- **Client-component hydration — resolved (v0.14+).** `nextcompile` now reads both - Next 14 `.json` and Next 15 `.js` client-reference-manifests, so `"use client"` - boundaries hydrate. Fixed generically, not per-app. +- **Client reference manifests — wired (v0.14+).** `nextcompile` now reads both + Next 14 `.json` and Next 15 `.js` manifests (previously the `.js` form was + ignored, leaving `loadClientManifest` null). This is the manifest *plumbing*; + it does not by itself guarantee a given app hydrates — that also needs the + app's client code + build-time `NEXT_PUBLIC_*`/auth env to be correct. - **Dynamic SSR (limitation 1) — open.** Needs a `workerd`-compatible Next server runtime (shim or vendored) so the externalized `app-page.runtime.prod.js` / `react-dom/server.edge` resolve at runtime. Tracked as engine work.