From 1a53bc493d4c00e1b34bb18cdfd38b39dd6310de Mon Sep 17 00:00:00 2001 From: nerdchanii Date: Fri, 29 May 2026 05:28:22 +0900 Subject: [PATCH] docs: organize examples by user scenario --- docs/public/examples/index.md | 37 +++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/public/examples/index.md b/docs/public/examples/index.md index 45c4d44..722c856 100644 --- a/docs/public/examples/index.md +++ b/docs/public/examples/index.md @@ -1,18 +1,16 @@ # Examples -Use this page as the canonical index for supported example shapes. Keep written -examples short and directly adaptable from runnable source instead of copying -large files into the docs. +Choose the example that matches how your app owns the realtime store. -## Canonical Examples Index +## Local Vite App -| Example | Purpose | Setup | Expected message flow | Cleanup | Copy-paste safety | -| --- | --- | --- | --- | --- | --- | -| [Local Vite provider example](#local-vite-provider-example) | Run a browser app that shares one store through `SocketProvider`. | From `example/`, run `npm install`, `npm run server`, and `npm run dev` in separate terminals. | The form sends `{ "key": "talk", "data": "" }` to `ws://localhost:3000`; the local server echoes valid topic messages; the `talk` handler appends payloads to chat state. | Close the browser tab to close the client socket. Stop the server with `Ctrl+C` to close connected clients. | Safe for sample apps and manual demos. For tests, copy the provider and hook shape, not the browser-only module-level `WebSocket` setup. | -| [React Router loader initial snapshot](#react-router-loader-initial-snapshot) | Seed a client-owned store from route loader data without adding a provider boundary. | Adapt into a React Router route with a loader that returns serializable initial messages. | The loader returns a snapshot; the client route creates the store after mount; `useSocket(store, "talk")` reads the seeded state and receives realtime updates. | The route cleanup closes the route-owned socket. Hook subscriptions clean up when the store provides unsubscribe callbacks. | Safe for tests or sample apps that pass an explicit store into components. Replace `wss://example.com/chat` with test or app infrastructure. | -| [Next.js App Router client island](#next-js-app-router-client-island) | Keep request data on the server and realtime store ownership inside a focused Client Component. | Adapt into App Router with a Server Component page and a `"use client"` island. | The server passes a serializable snapshot; the island creates one store per mounted boundary; `useSocket(store, "talk")` reads and sends through that store. | The island effect cleanup calls `socket.close()`. Hook subscriptions clean up on unmount or store/topic changes. | Safe for App Router sample apps and client-island tests. Do not copy it into a Server Component or shared module singleton. | +Use this example when you want the smallest runnable browser app with +`SocketProvider` and a local WebSocket server. -## Local Vite Provider Example +Key idea: + +- one browser app owns one store and shares it through `SocketProvider` +- a local server echoes topic messages so you can test the full flow quickly The Vite example includes a minimal local WebSocket echo server, so it does not need external infrastructure. From `example/`, install dependencies, then run @@ -54,10 +52,17 @@ export function TalkBox() { } ``` -Use `npm run docs:build` to verify the public docs site. - ## React Router Loader Initial Snapshot +Use this example when route loader data should seed the first render, but the +browser route still owns the realtime socket after mount. + +Key idea: + +- the loader returns only serializable snapshot data +- the client route creates the store and passes it directly to store-direct + hooks + React Router data loaders can fetch the request-scoped initial snapshot before the route renders. Pass that serializable data into a client-owned realtime component, create the store after mount, and use store-direct hooks instead of @@ -202,6 +207,14 @@ For equivalent server/client placement in App Router, see the ## Next.js App Router Client Island +Use this example when a Server Component should fetch request data and a +focused Client Component island should own the realtime connection. + +Key idea: + +- the server passes a serializable snapshot across the RSC boundary +- the client island creates and cleans up the `WebSocket` and `SocketStore` + In App Router, keep request-scoped data fetching in the Server Component and create the realtime store inside a focused Client Component island.