Skip to content

Add framework recipes for the Next.js, Astro, Remix, Hono and Tornado examples - #127

Merged
mehmetkose merged 1 commit into
mainfrom
docs-framework-recipes
Oct 22, 2026
Merged

mehmetkose merged 1 commit into
mainfrom
docs-framework-recipes

Conversation

@mehmetkose

Copy link
Copy Markdown
Owner

Five new recipes under Recipes, one for each runnable example that didn't have a docs page yet: Next.js, Astro, Remix 3, Hono and Tornado (Python). The game example already has one (Real-time action game). No library code changes (src/ is untouched).

What each page covers

Each page is written in plain, friendly language and has the same shape: the short version in a few bullets, install, where the shared client goes, how to use it in that framework's components, where the WebSocket server goes, the framework's catches, production, and things to try in the running example.

Page The framework-specific parts
nextjs.md A client from react-websocket/core that Server Components can import, hooks in Client Components, Suspense with browser(), and a custom server because route handlers can't accept upgrades
astro.md Islands sharing one client, a store for islands that hydrate late, Suspense in a client:only island, <ClientRouter /> with transition:persist, a custom element without React, and the server in dev (integration hook) and production (Express)
remix.md react-websocket/core with the example's bindings standing in for the hooks, client entries, the asset server's allow list, and upgrades on the Node server
hono.md Shared message types, upgradeWebSocket on Node.js, the Vite /ws proxy, room state refreshed by welcome, and one port in production
tornado.md The broadcast handler, check_origin, server pings, the message size limit, running with uv, and a client heartbeat

Other changes

  • docs/recipes.md: a Frameworks section with cards, above the real-world guides.
  • rspress.config.ts: a Frameworks sidebar group.
  • Links to the recipes from the home page, Getting started, the SSR and Without React guides, and each example's README.
  • A Documentation entry under [Unreleased] in the changelog.

Verified

  • Code blocks are copied or trimmed from the examples. 14 blocks match their example files exactly. Every line of each trimmed block comes from its example file, except shortened comments and narrowed imports.
  • Every TypeScript snippet type-checks against the library, in scratch copies of the examples (tsc, and astro check for the .astro files: 0 errors).
  • The Tornado heartbeat is the one piece of new code. Against a copy of the example's server with the reply added, the pong never reached the components and other clients saw no errors. When I paused the server, the client closed with 4000 within the timeout and reconnected after the resume. Without the server's return, every client reports a MessageError, as the page warns.
  • npm run docs:build and npm run check pass, and all 128 relative links and anchors in the new and edited pages resolve.
  • Checked in headless Chrome: the cards, the sidebar group and the tables, down to 520px wide.

… examples

One recipe per example, in plain and friendly language: where the shared
client goes, how to use it in that framework's components, where the
WebSocket server goes, the framework's catches, production, and things
to try in the running example.

- Next.js: a client from react-websocket/core, hooks in Client
  Components, Suspense with browser(), and a custom server for upgrades
- Astro: islands sharing one client, a store for islands that hydrate
  late, client:only Suspense, ClientRouter with transition:persist, a
  custom element without React, and the server in dev and production
- Remix 3: react-websocket/core with bindings that stand in for the
  hooks, client entries, the asset server's allow list, and upgrades
  on the Node server
- Hono: shared message types, upgradeWebSocket on Node.js, the Vite
  proxy, room state refreshed by welcome, and one port in production
- Tornado: the broadcast handler, check_origin, server pings, the
  message size limit, running with uv, and a client heartbeat

The recipes page gets a Frameworks section and the sidebar a Frameworks
group. The home page, Getting started, the SSR and Without React guides
and each example's README link to them.

Code blocks are copied or trimmed from the examples and type-checked
against the library (tsc, and astro check for .astro files). The
Tornado heartbeat is the one new piece of code: it was run against a
copy of the example's server, which answered the pings, and a paused
server was noticed within the timeout.
@mehmetkose
mehmetkose merged commit a335125 into main Oct 22, 2026
7 checks passed
@mehmetkose
mehmetkose deleted the docs-framework-recipes branch October 22, 2026 22:49
@mehmetkose mehmetkose mentioned this pull request Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant