Framework-first islands (streaming SSR, shared Context & Hydration) #1239

arthurpeixotomelo · 2025-10-12T19:28:21Z

arthurpeixotomelo
Oct 12, 2025

Goal: Let framework components (React/Preact/Solid/Svelte, etc.) behave inside Astro as they do natively: nestable, context‑preserving, and streamable—without abandoning Astro’s islands and “zero JS by default.”
Approach: Adopt Vite’s Environment API as the foundation, make same‑framework nested islands join the same root by default (shared context), and pass through framework streaming SSR in adapters. Keep changes focused on integration surfaces rather than adding Astro‑specific context mechanisms.

Most pain points come from isolated roots and lack of SSR streaming/composition, not from the absence of Astro‑side context features.
By aligning with frameworks’ own SSR/hydration capabilities and Vite’s Environment API, we unlock:
- Framework context across nested islands (no forced “wrap the whole section in framework X”).
- Partial/parallel streaming for slow subtrees.
- Cleaner SSR/client/edge splits (especially for CSS‑in‑JS).
- A foundation for optional experiments like RSC.

Standardize browser/ssr/edge/worker environments in dev/build; adapters receive environment metadata; integrations can expose environment‑specific entry points/conditions.
Breaking change (already planned for V6).
Addresses:
- CSS‑in‑JS stability through predictable SSR/client splits (778).
- Clean prerequisites for future experiments like RSC.

When an island of framework X is nested under a parent island also using X, hydrate it under the parent’s existing root by default (preserving context/effects).
Provide an explicit opt‑out to force a new root when needed.
Addresses:
- UI framework contexts between islands and library composition (Radix, HeadlessUI) (742).
- Nested hydrated components sharing context (18).
- Reduces the need for third library tools for state management when needing to share state between islands and/or an "Astro Context API" where frameworks context can/should suffice (1084, 445, 731).

Allow integrations to return streamable SSR and compose these streams in Astro/adapters with stable fragment placeholders and support for Suspense/partial flush.
Update adapter interfaces for Node and Edge/Workers to support interleaved flush safely.
Addresses:
- Parallel/streaming SSR so slow framework subtrees don’t block the document (659).
- Improves UX in nested/island‑heavy pages (742).

Emphasize a renderer contract over Astro‑specific mechanisms:
- Shared‑root compatibility (mount a child under an existing root to preserve framework semantics).
- Streaming SSR capability when frameworks support it.
- Environment‑specific entries using the Environment API.
- Hydration options exposed cleanly via integrations (e.g., pass React’s onRecoverableError).
Addresses:
- Hydration options for better error reporting (498).
- CSS‑in‑JS behavior aligns with environment‑aware SSR and integration hooks (778).

(742) Framework contexts between islands: child islands of the same framework join the parent root by default, so library patterns (Radix, HeadlessUI) “just work.”
(18) Nested hydrated components: shared‑root hydration preserves context across nested islands.
(659) Parallel/streaming: pass through framework streaming SSR and compose in adapters so slow parts don’t block the page.
(778) CSS‑in‑JS: environment‑aware builds and clear integration contracts reduce workarounds and make SSR outputs predictable.
(498) Hydration options: expose framework‑specific hydration knobs via integrations for better error capture and control.