Pre-flight checklist
Problem or use case
ssr is one of the three modules still marked Experimental, yet it is foundational to bQuery's "one stack, client and server" promise — teams cannot commit production SSR on a surface that may break between minors. The module's surface has churned across consecutive releases (flushBoundary, createSSRCache, createSSRMetrics, createEdgeHandler landed in 1.11.0; cache-aware renderToResponse and multi-chunk renderToStream evolved again by 1.14.0). There is no published checklist for what would move ssr out of Experimental, so adopters have no signal for when it is safe to depend on.
Proposed solution
Define and publish concrete exit criteria for ssr, then freeze the public API for at least one full minor cycle to demonstrate stability. Criteria should cover: (a) a frozen, documented export surface; (b) a stated minimum test-coverage bar including streaming, suspense streaming, island hydration, and edge-handler paths; (c) resolution of the dependent capability gaps tracked in tickets #128, #129, and #130; (d) a documented SSR support matrix per runtime (Node ≥ 24, Bun, Deno, edge). This ticket is the tracking issue; #128–#130 are the substantive prerequisites.
Possible API or UX shape
No new public API is required for the freeze itself. The deliverable is a "Stability" subsection in the SSR guide:
## Stability: targeting Stable in 1.15.0
Exit criteria:
- [ ] Public exports frozen for one minor (no additive breaking changes)
- [ ] Directive parity resolved or boundary documented (#128)
- [ ] Resumability model finalized (#129)
- [ ] Hydration-mismatch handling productionized (#130)
- [ ] Per-runtime support matrix published
Frozen surface: renderToString, renderToStream, renderToStreamSuspense, defer,
renderToResponse, createSSRCache, createSSRMetrics, createEdgeHandler,
hydrateOnVisible|Idle|Interaction|Media, createResumableState
Alternatives considered
Leaving ssr Experimental indefinitely while it accretes features — rejected because the competitive frameworks (SvelteKit, Nuxt, React 19 SSR) all offer production-grade SSR, and an Experimental label is the single biggest blocker to bQuery being evaluated for real apps. Promoting without a freeze period — rejected because it would violate the module's own semver promise.
Relevant area
ssr
Additional context
The SSR guide currently lists renderToString support for only bq-text, bq-html, bq-if, bq-show, bq-for, bq-class, bq-style, bq-bind:*, and createResumableState() is described as "a tiny key/value collector" — both are tracked as prerequisites below. Competitive baseline: React 19 shipped stable Server Components and streaming SSR in December 2024; SvelteKit and Nuxt offer mature SSR with file-based data loading.
Pre-flight checklist
Problem or use case
ssris one of the three modules still marked Experimental, yet it is foundational to bQuery's "one stack, client and server" promise — teams cannot commit production SSR on a surface that may break between minors. The module's surface has churned across consecutive releases (flushBoundary,createSSRCache,createSSRMetrics,createEdgeHandlerlanded in 1.11.0; cache-awarerenderToResponseand multi-chunkrenderToStreamevolved again by 1.14.0). There is no published checklist for what would movessrout of Experimental, so adopters have no signal for when it is safe to depend on.Proposed solution
Define and publish concrete exit criteria for
ssr, then freeze the public API for at least one full minor cycle to demonstrate stability. Criteria should cover: (a) a frozen, documented export surface; (b) a stated minimum test-coverage bar including streaming, suspense streaming, island hydration, and edge-handler paths; (c) resolution of the dependent capability gaps tracked in tickets #128, #129, and #130; (d) a documented SSR support matrix per runtime (Node ≥ 24, Bun, Deno, edge). This ticket is the tracking issue; #128–#130 are the substantive prerequisites.Possible API or UX shape
No new public API is required for the freeze itself. The deliverable is a "Stability" subsection in the SSR guide:
Alternatives considered
Leaving
ssrExperimental indefinitely while it accretes features — rejected because the competitive frameworks (SvelteKit, Nuxt, React 19 SSR) all offer production-grade SSR, and an Experimental label is the single biggest blocker to bQuery being evaluated for real apps. Promoting without a freeze period — rejected because it would violate the module's own semver promise.Relevant area
ssrAdditional context
The SSR guide currently lists
renderToStringsupport for onlybq-text, bq-html, bq-if, bq-show, bq-for, bq-class, bq-style, bq-bind:*, andcreateResumableState()is described as "a tiny key/value collector" — both are tracked as prerequisites below. Competitive baseline: React 19 shipped stable Server Components and streaming SSR in December 2024; SvelteKit and Nuxt offer mature SSR with file-based data loading.