Add streaming to readme

JoviDeCroock · JoviDeCroock · commit 7cec04f87139 · 2026-02-20T07:28:02.000+01:00
diff --git a/README.md b/README.md
@@ -144,6 +144,106 @@ main().catch((error) => {
 
 ---
 
+### Streaming
+
+> [!NOTE]
+> This is an early version of our streaming implementation.
+
+Preact supports streaming HTML to the client incrementally, flushing `<Suspense>` fallbacks immediately and replacing them with the resolved content as data arrives. This reduces Time to First Byte and allows the browser to start parsing earlier.
+
+Suspended subtrees are rendered into a hidden `<div>` and swapped into place on the client via a small inline script. When rendering a full HTML document (component tree rooted at `<html>`), a `<!DOCTYPE html>` declaration is prepended automatically and deferred content is injected before the closing `</body>` tag to keep the markup valid.
+
+#### `renderToReadableStream` — Web Streams (Edge / Deno / Bun / Cloudflare Workers)
+
+```jsx
+import { renderToReadableStream } from 'preact-render-to-string/stream';
+import { Suspense, lazy } from 'preact/compat';
+
+const Profile = lazy(() => import('./Profile'));
+
+const App = () => (
+	<html>
+		<head><title>My App</title></head>
+		<body>
+			<Suspense fallback={<p>Loading profile…</p>}>
+				<Profile />
+			</Suspense>
+		</body>
+	</html>
+);
+
+// Works in any Web Streams environment (Deno, Bun, Cloudflare Workers, …)
+export default {
+	fetch() {
+		const stream = renderToReadableStream(<App />);
+
+		// stream.allReady resolves once all suspended content has been flushed
+		return new Response(stream, {
+			headers: { 'Content-Type': 'text/html' }
+		});
+	}
+};
+```
+
+The returned `ReadableStream` has an extra `allReady: Promise<void>` property that resolves once every suspended subtree has been written. Await it before sending the response if you need the complete document before anything is flushed (e.g. for static export).
+
+```js
+const stream = renderToReadableStream(<App />);
+await stream.allReady; // wait for full render
+```
+
+#### `renderToPipeableStream` — Node.js Streams
+
+```jsx
+import { createServer } from 'node:http';
+import { renderToPipeableStream } from 'preact-render-to-string/stream-node';
+import { Suspense, lazy } from 'preact/compat';
+
+const Profile = lazy(() => import('./Profile'));
+
+const App = () => (
+	<html>
+		<head><title>My App</title></head>
+		<body>
+			<Suspense fallback={<p>Loading profile…</p>}>
+				<Profile />
+			</Suspense>
+		</body>
+	</html>
+);
+
+createServer((req, res) => {
+	res.setHeader('Content-Type', 'text/html');
+
+	const { pipe, abort } = renderToPipeableStream(<App />, {
+		onShellReady() {
+			// Called once the synchronous shell is ready to stream.
+			pipe(res);
+		},
+		onAllReady() {
+			// Called once every suspended subtree has been flushed.
+		},
+		onError(error) {
+			console.error(error);
+			res.statusCode = 500;
+		}
+	});
+
+	// Optional: abort the render after a timeout
+	setTimeout(abort, 10_000);
+}).listen(8080);
+```
+
+| Option | Description |
+|---|---|
+| `onShellReady()` | Called synchronously once the initial shell has been rendered and streaming is about to start. Pipe here for fastest TTFB. |
+| `onAllReady()` | Called after all `<Suspense>` boundaries have resolved and the stream is complete. |
+| `onError(error)` | Called for render errors inside suspended subtrees. |
+
+Calling `abort()` stops the render and destroys the stream; any pending suspended subtrees are dropped.
+
+---
+
 ### License
 
 [MIT](http://choosealicense.com/licenses/mit/)
