Skip to content

[Feature]: Promote ssr to Stable — freeze public API and define exit criteria #127

Description

@JosunLP

Pre-flight checklist

  • I searched existing issues and did not find a duplicate request.
  • I explained the problem or use case, not just the desired API.

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ssrChanges to the ssr module

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions