✨ feat(react-web): Isomorphic OptimizationProvider for SSR (NT-3560)

[Tim Beyer (TimBeyer)]

Summary

Fixes NT-3560: OptimizationProvider returned null during server-side rendering, producing a blank page in Next.js App Router and any SSR environment (and failing the JavaScript-disabled E2E tests added in #348).

The root cause was a React-lifecycle mistake, not mutable state or browser globals. The fix makes the React provider isomorphic: it renders personalized content on the server from a read-only snapshot, then upgrades to the live stateful SDK on the client — so the same hooks and <OptimizedEntry> work in both environments and the developer never branches on typeof window.

Proven end-to-end: the nextjs-sdk_ssr reference app now renders fully-personalized server HTML with JavaScript disabled, and the full SSR E2E suite passes (26/26), including the "SSR first-paint state" and "Variant Resolution (SSR, JavaScript disabled)" blocks that fail on main.

---

The problem

The browser SDK (ContentfulOptimization) is stateful and browser-bound: its constructor reads localStorage/document.cookie, attaches listeners, and registers a window singleton. It cannot be constructed during server rendering, and React never runs effects (useEffect/useLayoutEffect) on the server — only render and useState/useMemo initializers.

The old provider created the SDK inside useLayoutEffect and gated all children on that SDK:

const [state] = useState(() => ({ isReady: false, sdk: undefined }))
useLayoutEffect(() => { /* new ContentfulOptimization(...) */ }, [])
if (!state.isReady) return null   // ← on the server, isReady is ALWAYS false

So the server rendered an empty tree. With JS disabled that is a permanently blank page; with JS on, a blank first paint until hydration.

Design principle: split by capability, not by environment

The key realization is that rendering personalized content does not require the stateful browser SDK — only the personalization data and the pure logic that resolves it. The SDK surface splits into three tiers by what each capability needs:

Tier	Members	Needs a browser?	Server behavior
Resolve	resolveOptimizedEntry, getMergeTagValue, getFlag	No — pure functions	Identical to the client
Read state	states.{consent, profile, selectedOptimizations, canOptimize, …}	No	Static values from the request snapshot
Act / track	identify, page, track, tracking.*, trackCurrentPage	Yes	Inert no-ops (no user interaction to record on the server)

The resolve tier already lives on CoreBase (shared by both the stateful and stateless runtimes), so variant resolution works server-side today. Reading state needs only a static view of the request's evaluated data. Only interaction tracking genuinely needs the browser — and it is effect-only by nature, so it never executes during a server render.

The governing axis is render-time vs. effect-time, not "isomorphic vs. not": render-time code runs on the server and must be safe; effect-time code never runs there.

The seam: one interface, one switch site

OptimizationRuntime is the single interface the hooks and components bind to. It is derived from the stateful runtime via Pick<CoreStateful, …>, so the live browser SDK satisfies it by construction and a server implementation is forced to match the same signatures. Two runtimes implement it:

• The live SDK (ContentfulOptimization) on the client after hydration.
• A snapshot runtime (createSnapshotRuntime, on the new @contentful/optimization-core/runtime subpath) for the server render and the initial client render. Its resolve methods delegate to the shared static resolvers (no ApiClient, no browser globals), its states are static observables over a serialized OptimizationData snapshot, and its actions are inert no-ops that warn in development.

OptimizationProvider is the only place that chooses the backing. The developer calls useOptimization() and receives one runtime whose behavior is correct wherever it runs — never a null guard, never a throwing accessor on the server.

The render → hydrate flow

SERVER                                   BROWSER
------                                   -------
1. Resolve request OptimizationData
2. Render with a snapshot runtime   ──►  3. Paint personalized HTML immediately
   • render() + useState run                 (also what a JS-disabled browser or
   • effects DO NOT run                        crawler sees)
   • getServerSnapshot supplies state
   • OptimizedEntry resolves variants   ──►  4. Download JS
                                             5. Hydrate: first render reuses the SAME
                                                snapshot, so markup matches (no mismatch)
                                             6. Effect constructs the live SDK,
                                                hydrates it, swaps the context
                                             7. Interactive: state changes re-render

Hydration determinism contract: the serialized snapshot fed to the server render is the exact value the client provider is seeded with; variant resolution is a pure function of (baselineEntry, selectedOptimizations), so both sides produce identical markup. Later divergence (e.g. a newer locally-cached profile) is reconciled after hydration by a normal re-render — the React-blessed path.

API changes

New

• @contentful/optimization-core/runtime — OptimizationRuntime (interface), createSnapshotRuntime / SnapshotRuntime, OptimizationSnapshot. Also staticObservable on the signals surface. Placed on a dedicated subpath so it stays out of the always-loaded base bundle and tree-shakes for consumers that never render server-side.
• @contentful/optimization-web/runtime — pass-through re-export mirroring the existing core-sdk/api-client/api-schemas subpaths.
• WebOptimizationRuntime (react-web) — composes the universal runtime with the browser-only surface (tracking, trackCurrentPage); createWebSnapshotRuntime provides the server backing.

Changed (breaking, pre-GA)

• OptimizationProvider/OptimizationRoot now render on the server. The React context value is { sdk, isReady, error } where sdk is the always-present isomorphic runtime.
• useOptimization() no longer throws at render time on the server; it returns the isomorphic runtime (snapshot-backed on the server, live SDK after hydration) and throws only when used outside a provider.
• Read hooks pass a real getServerSnapshot to useSyncExternalStore.

Deprecated (kept working, with guidance)

• NextjsOptimizationState → pass server data to the provider via serverOptimizationState (the provider hydrates the live SDK itself). Retained for configuring a provider without server data and hydrating page-specific data later.
• ServerOptimizedEntry → prefer the isomorphic OptimizedEntry. Retained for pure zero-JavaScript Server Component rendering with no live updates.

Reference implementation (nextjs-sdk_ssr)

• The layout resolves the request optimization data and passes it to OptimizationRoot via serverOptimizationState, so the provider renders identified/personalized state on the server.
• Resolution is wrapped in a request-scoped React cache() helper (getServerOptimizationData) shared by the layout and pages, emitting exactly one Experience page() per request.
• Pages render entries with OptimizedEntry; the redundant <NextjsOptimizationState> was removed.
• SKIP_NO_JS dropped from the E2E flags — the JS-disabled first-paint and variant-resolution suites now pass.

The React Server Component boundary (the one honest limitation)

React hooks cannot run inside a true async Server Component — that is a React rule, not an SDK limitation. "Isomorphic" applies to Client Components ('use client') that are server-rendered for first paint and then hydrate, which covers OptimizedEntry and every read hook. Code that runs only in an RSC (the fetch/decide step) uses the same-named imperative method runtime.resolveOptimizedEntry(entry, selectedOptimizations) — no second vocabulary. This is documented in the new concept doc.

Documentation

• New concept: documentation/concepts/server-side-rendering-and-hydration.md (capability tiers, the runtime seam, render/hydrate flow, RSC boundary, determinism contract).
• Next.js SSR guide + optimization-nextjs/optimization-react-web READMEs + nextjs-sdk_ssr README updated to lead with serverOptimizationState + isomorphic OptimizedEntry.
• Deprecation notes added across the hybrid guide, hybrid README, and the locale / entry-resolution / node-tracking / profile-sync concept docs.

Validation

Run under the pinned Node from .nvmrc (24.15.0):

• Unit: core 287/287, react-web 107/107, nextjs 27/27 — including new SnapshotRuntime, staticObservable, and SSR-first-paint tests.
• Lint / typecheck: clean (the only lint output is 4 expected @deprecated-usage warnings in tests that exercise the deprecated components).
• Build: full workspace build:pkgs succeeds; the new ./runtime subpath emits declarations for core and web.
• Bundle size: size:check green. The ./runtime split returned index.cjs to its exact baseline; the index.mjs gzip budget was raised ~800 B to absorb shared-chunk re-attribution from adding the entry (real per-consumer payload is essentially unchanged).
• E2E: nextjs-sdk_ssr Playwright suite 26/26 with JavaScript enabled and disabled, including the Hydration check that a consented SSR handoff issues no duplicate client Experience request.

Note

The repo pins Node 24.15.0 (.nvmrc). Node 25 ships a native localStorage that conflicts with the happy-dom mock and makes several SDK unit tests spuriously fail; use the pinned version.

Update: reference implementations migrated + SSR entry-rendering fixes

Both Next.js reference apps now use the recommended pattern end-to-end, which surfaced (and fixed) the remaining server-render gaps flagged as Risk A in the plan:

• nextjs-sdk_ssr and nextjs-sdk_hybrid now seed OptimizationRoot with serverOptimizationState in the layout and render entries with the isomorphic OptimizedEntry (the deprecated NextjsOptimizationState / ServerOptimizedEntry are gone from both apps).
• Migrating EntryCard to <OptimizedEntry> exposed that server HTML rendered a hidden loading target instead of visible variant content. Fixed with three coordinated SDK changes so the server render and the client's first render agree (no hydration mismatch):
  • OptimizedEntryController now primes selectedOptimizations/state from sdk.states.*.current at construction (previously only in connect(), a client effect), so the constructor-time snapshot resolves the variant.
  • useOptimizedEntry seeds isPresentationReady from context readiness instead of an effect (effects don't run on the server).
  • SnapshotRuntime reports a settled (success) experience request state — a snapshot has no request in flight for the render it backs — so OptimizedEntry presents content rather than a loading state.
• Also fixed an injected-SDK provider case (unrelated to the migration but found while running under the pinned Node): serverOptimizationState now drives first paint for injected SDKs too, and an injected SDK with only onStatesReady keeps backing the render directly.

Validation for the migration: nextjs-sdk_ssr SSR E2E 26/26 (incl. JS-disabled variant resolution now rendering through OptimizedEntry), nextjs-sdk_hybrid CSR+HYDRATION E2E 24/24, full-graph size:check green.

Follow-ups (not in this PR)

• The index.mjs budget bump is a measurement artifact of adding the ./runtime entry; a targeted chunkSplit change could restore the baseline without touching the budget.

🤖 Generated with Claude Code

[Charles Hudson (phobetron)]

Could this be supplied by the Next.js SDK, so the consumer won't need to have this boilerplate? Is there any possible need to customize the functionality?

[Tim Beyer (TimBeyer)]

Partly. Only the cache() wrapping and reading cookies()/headers() are truly mechanical — the consent gate (app-specific cookie name + scheme), locale, and pagePayload/experienceOptions are all things a real app customizes, so an SDK-owned version would have to re-accept them as options and wouldn't save much. There's also a deliberate design constraint: getNextjsServerOptimizationData takes cookies/headers as params rather than importing next/headers itself (keeps it testable and Pages-Router-portable), and an auto-reading convenience would break that decoupling.

A reference implementation is also meant to show this wiring explicitly, so I'd lean toward keeping it here as teaching material. Happy to file a follow-up for an optional thin SDK helper (a cache-wrapped variant that reads next/headers and takes an optional consent predicate) if you think it's worth it — flagging rather than doing it in this PR.

[Charles Hudson (phobetron)]

Would this value ever change? Is it still necessary?

[Tim Beyer (TimBeyer)]

Good catch — it no longer carries independent meaning. After the isomorphic rework isReady is equivalent to sdk !== undefined: it starts true (a snapshot always backs first paint) and only flips to false in the initialization-error path, where runtime is set to undefined at the same time.

Removed it from OptimizationContextValue/ProviderState and derived readiness from sdk presence in the consumers (LiveUpdatesProvider, useOptimizedEntry, plus the SSR/hybrid reference apps). useOptimizedEntry's own returned isReady (presentation-readiness from the controller snapshot) is a separate thing and stays.

Done in fb3d43b4 (SDK) and 41361082 (reference apps).

[Charles Hudson (phobetron)]

During this time, I usually tell agents "make clean breaking changes; this is not in production so there should be no deprecations or concerns for migrations and/or backwards compatibility". It would be nice to see the full cleanup and how it works in the hybrid reference implementation.

[Tim Beyer (TimBeyer)]

Agreed on the clean-break approach. That specific note was already removed in a9484384 (the hybrid impl now uses serverOptimizationState and OptimizedEntry), and I've now done the full cleanup of the two deprecated APIs this PR was carrying:

• NextjsOptimizationState — deleted (18c4c2a0). Its only residual use (config-seed a provider, hydrate page data later) is served directly by the public hydrateOptimizationData from @contentful/optimization-web/bridge-support, which the docs now point to.
• ServerOptimizedEntry — undeprecated and renamed to ServerOnlyOptimizedEntry (3b06c6db). The zero-client-JS Server Component entry is a genuinely distinct capability from the isomorphic OptimizedEntry; only the name collided (it read as "the server variant of OptimizedEntry", misleading now that OptimizedEntry also server-renders). "Server-only" names the defining trait: it ships no client JS for the entry.

Both are clean breaking changes with no compatibility alias. The hybrid reference app is fully migrated off the deprecated APIs.

[Charles Hudson (phobetron)]

All in all, this seems like a more advanced solution in the same direction as David Nalchevanidze (@nalchevanidze)'s original stub idea.

[Charles Hudson (phobetron)]

We should probably just remove anything that would be deprecated; not sure if this would be our fully-accepted solution yet, but it'll be easier to see and there'll be no cleanup tasks afterward if this does become the accepted solution.

[Lotfi Anwar L Arif (Lotfi-Arif)]

isReady implementations/react-web-sdk/src/App.tsx:25, AnalyticsEventDisplay.tsx:154, ControlPanel.tsx:196 all destructure isReady from useOptimizationContext(), which no longer has that
field. isReady is always undefined → every if (!sdk || !isReady) guard is permanently true → all SDK-gated effects (subscriptions, analytics, consent) silently never fire in this reference implementation.

[Lotfi Anwar L Arif (Lotfi-Arif)]

hasConsent() drops its argument, SnapshotRuntime.ts:153 declares hasConsent() with no parameter. The OptimizationRuntime interface picks hasConsent(name: string) from CoreStateful. TypeScript accepts narrower signatures, so no type error. But web-sdk/EntryInteractionRuntime and other callers pass event names through this interface during SSR / first-client render and always get snapshot.consent === true, bypassing partial-consent gating.

[Tim Beyer (TimBeyer)]

Good catch — fixed. SnapshotRuntime.hasConsent now takes hasConsent(name: string) (matching the OptimizationRuntime/CoreStateful signature) and resolves through the same allow-list-aware logic the live SDK uses (CONSENT_EVENT_TYPE_MAP + the granted-consent short-circuit), rather than returning snapshot.consent === true.

To make that possible the snapshot now carries allowedEventTypes (defaults to fail-closed DEFAULT_ALLOWED_EVENT_TYPES), and the React provider seeds it from the same value the live SDK is configured with (the web default is ['identify','page']), so pre/post-hydration answers match.

One clarification on the report: I traced every hasConsent caller — EntryInteractionRuntime and the others call it on the live ContentfulOptimization in browser-only effects, never on the snapshot during SSR/first render, so there was no active mis-gating in our own code. It was a latent public-contract bug regardless, now closed. Added unit tests covering the allow-list paths.

[Lotfi Anwar L Arif (Lotfi-Arif)]

optimizationPossible: staticObservable(true) hardcoded — SnapshotRuntime.ts:97. For a visitor with no consent, the live SDK produces optimizationPossible=false, but the snapshot reports true. When the live SDK hydrates and subscribes via OptimizedEntryController.resubscribe(), the true→false flip triggers updateSnapshot(), causing the controller to re-evaluate and potentially flash from resolved variant → loading/baseline.

[Tim Beyer (TimBeyer)]

Fixed. optimizationPossible is no longer hardcoded — the snapshot now computes it with the same rule as the live SDK (consent === true, or the allow-list contains an optimization-unlocking event type), seeded from the allowedEventTypes the provider now threads in. So a no-consent / empty-allow-list visitor reports false on both sides, and the shipped default (['identify','page']) reports true on both — no true→false flip on hydration, no resolved-variant → baseline flash.

Added unit tests for the pre-consent false (empty allow-list) and true (unlocking type allow-listed) cases.