|
| 1 | +# Simple stream 🌊 |
| 2 | + |
| 3 | +Suspend Astro components with fallback content. Like React Server Components, but Just HTML ™️ |
| 4 | + |
| 5 | +```astro |
| 6 | +--- |
| 7 | +import { Suspense, ResolveSuspended } from 'simple-stack-stream/components'; |
| 8 | +--- |
| 9 | +
|
| 10 | +<h1>Simple stream</h1> |
| 11 | +
|
| 12 | +https://github.com/bholmesdev/simple-stack/assets/51384119/99ed15a4-5a70-4f19-bc2a-712d4039c0a7 |
| 13 | +
|
| 14 | +<!--Suspend slow-to-load content--> |
| 15 | +<Suspense> |
| 16 | + <VideoPlayer /> |
| 17 | + <!--Show fallback content--> |
| 18 | + <LoadingSkeleton slot="fallback" /> |
| 19 | +</Suspense> |
| 20 | +
|
| 21 | +<Footer /> |
| 22 | +<!--Render suspended content--> |
| 23 | +<ResolveSuspended /> |
| 24 | +``` |
| 25 | + |
| 26 | +## Installation |
| 27 | + |
| 28 | +Simple stream is an Astro integration. You can install and configure this via the Astro CLI using `astro add`: |
| 29 | + |
| 30 | +```bash |
| 31 | +npm run astro add simple-stack-stream |
| 32 | +``` |
| 33 | + |
| 34 | +## Usage |
| 35 | + |
| 36 | +Simple stream exposes a "Suspense" utility to show fallback content while your server-side components load. |
| 37 | + |
| 38 | +### `Suspense` |
| 39 | + |
| 40 | +`<Suspense>` is a wrapper component for any content you want to load out-of-order with a fallback. Pass any suspended content as children, and use `slot="fallback"` to define your fallback: |
| 41 | + |
| 42 | +```astro |
| 43 | +--- |
| 44 | +import { Suspense } from 'simple-stack-stream/components'; |
| 45 | +--- |
| 46 | +
|
| 47 | +<Suspense> |
| 48 | + <VideoPlayer /> |
| 49 | + <p slot="fallback">Loading...</p> |
| 50 | +</Suspense> |
| 51 | +``` |
| 52 | + |
| 53 | +⚠️ **Client JS is required** for suspended content to render. For progressive enhancement, we recommend including `<noscript>` content as part of your fallback: |
| 54 | + |
| 55 | +```astro |
| 56 | +--- |
| 57 | +import { Suspense } from 'simple-stack-stream/components'; |
| 58 | +--- |
| 59 | +
|
| 60 | +<Suspense> |
| 61 | + <VideoPlayer /> |
| 62 | + <div slot="fallback"> |
| 63 | + <noscript>JavaScript is required for video playback.</noscript> |
| 64 | + <p>Loading...</p> |
| 65 | + </div> |
| 66 | +</Suspense> |
| 67 | +``` |
| 68 | + |
| 69 | +### `ResolveSuspended` |
| 70 | + |
| 71 | +The `<ResolveSuspended />` component renders all suspended content. This component should be placed at the _end_ of your HTML document, ideally before the closing `</body>` tag. This prevents `ResolveSuspended` from blocking components below it when [using Astro SSR](https://docs.astro.build/en/guides/server-side-rendering/#html-streaming). |
| 72 | + |
| 73 | +We recommend [a reusable Layout](https://docs.astro.build/en/core-concepts/layouts/) to ensure this component is present wherever `<Suspense>` is used: |
| 74 | + |
| 75 | +```astro |
| 76 | +--- |
| 77 | +// src/layouts/Layout.astro |
| 78 | +import { ResolveSuspended } from 'simple-stack-form/components'; |
| 79 | +--- |
| 80 | +
|
| 81 | +<!DOCTYPE html> |
| 82 | +<html lang="en"> |
| 83 | +<head>...</head> |
| 84 | +<body> |
| 85 | + <slot /> |
| 86 | + <ResolveSuspended /> |
| 87 | +</body> |
| 88 | +</html> |
| 89 | +``` |
0 commit comments