# Redweb

> Server-rendered TypeScript/TSX sites with server-owned state/actions and routed WebSockets on Node.js.

> Documentation for Redweb 0.13.2. Install that exact version when following these examples.

TSX is not React. State is assignment-driven. Shared memory is not durable storage. Socket routes select services; message types select handlers. Applications own identity, authorization, persistence, and delivery reconciliation.

## Guides and complete recipes

- [Choose a starter and build a working app](/docs/reference/0.13.2/getting-started.md): Requirements, fit, development, tests, and production boundaries.

- [Build a private realtime dashboard](/docs/reference/0.13.2/guides/realtime-dashboard.md): Persistent SQLite cards, account-private updates and sign-out across tabs, with explicit single-process limits.

- [Render JSX without React](/docs/reference/0.13.2/guides/jsx-without-react.md): TypeScript pages, a shared layout and external CSS, rendered on the server without browser framework code.

- [Build a chatroom with live presence](/docs/reference/0.13.2/guides/chatroom.md): Reusable server-side components, validated forms and disconnect-aware presence, without custom browser socket glue.

- [Share typed WebSocket contracts](/docs/reference/0.13.2/guides/typed-websockets.md): One match route, separate join/move/resume handlers and validated client/server payloads from the same schema.

- [Serve HTTP and WebSockets on one port](/docs/reference/0.13.2/guides/http-websocket.md): An Express endpoint and raw socket route share one listener with one explicit shutdown owner.

- [Upgrade an existing Redweb application](/docs/reference/0.13.2/migration.md): Historical socket defaults, asynchronous ownership, HTML migration and version-matched verification.

- [Initialization and diagnostics](/docs/reference/0.13.2/cli.md): Noninteractive setup, safe existing-project adoption, and structured repair guidance.

- [Develop with browser refresh and safe inspection](/docs/reference/0.13.2/development.md): Loopback-only refresh with an explicit edit guard, plus bounded metadata and reactive update inspection without application values.

- [Understand runtime failures before retrying](/docs/reference/0.13.2/runtime-diagnostics.md): Safe authentication, authorization, validation and application errors, with actual retry and cancellation guarantees.

- [Optional read-only agent documentation access](/docs/reference/0.13.2/agent-access.md): Configure local MCP search and exact recipe retrieval without adding dependencies to Redweb servers.

- [Pages, components, state, actions, and CSS](/docs/reference/0.13.2/live-html.md): Server-side TSX, automatic updates, keyed lists, lifecycle, and static export.

- [Typed socket routes and handlers](/docs/reference/0.13.2/socket-contracts.md): Shared validation, client/server types, protocol errors, and join/move/resume.

- [Private rooms and shared request identity](/docs/reference/0.13.2/room-authorization.md): Explicit entry policies, bounded authorization, trusted context, publication and revocation.

- [Deploy and operate socket services](/docs/reference/0.13.2/operations.md): Readiness, shutdown, capacity, reconnection, and distributed boundaries.

- [Production guarantees and limits](/docs/reference/0.13.2/production-contract.md): Resource ownership, delivery semantics, compatibility, and release gates.

- [Recorded verification evidence](/docs/reference/0.13.2/verification.md): Historical measurements and their exact scope; not proof of a newer release.

- [Release status](/docs/reference/0.13.2/release-status.md): Acceptance checklist, completed increments, and remaining publication or deployment boundaries.

- [Choose and verify a release](/docs/reference/0.13.2/release-trust.md): Maintained runtimes, compiler/browser verification boundaries, pinned packages, registry signatures, provenance and support limits.

- [Realtime starter](/docs/reference/0.13.2/recipes/realtime.md): `CounterPage` owns its state on the server. `shared: true` deliberately shares the counter between visitors.

- [Chat starter](/docs/reference/0.13.2/recipes/chat.md): `src/chatroom.tsx` is the canonical Redweb chat component example, included directly rather than a second implementation.

- [Site starter](/docs/reference/0.13.2/recipes/site.md): `defineSite` supplies one layout and stylesheet for `/` and `/about`. Each page sets its own title.

- [Socket starter](/docs/reference/0.13.2/recipes/socket.md): This is a WebSocket service, not an HTML page. Connect to `ws://localhost:8181/match?redwebVersion=1`.

- [Dashboard starter](/docs/reference/0.13.2/recipes/dashboard.md): This recipe combines decorator-first pages, reusable live cards, validated actions, and real SQLite persistence. It is an application example, not an authentication framework or managed database.

- [Http-ws starter](/docs/reference/0.13.2/recipes/http-ws.md): One Node server answers ordinary HTTP requests and upgrades `/chat` connections to WebSockets. HTTP paths select Express services; a socket URL selects a route and each message's `type` selects a handler. No socket decorators or secondary `message.action` dispatcher are needed.

- [One identity for a page and a protected room](/docs/reference/0.13.2/examples/room-access.md): A complete local demonstration of shared authentication, decorator-first server HTML and explicitly authorized raw socket room entry.

- [HTTP and WebSockets on one listener](/docs/reference/0.13.2/examples/shared-server.md): Build the Express side without binding, attach route classes to the same Node server, and explicitly give the socket service responsibility for listening and cleanup.

- [Server state and reusable TSX components](/docs/reference/0.13.2/examples/live-html.md): Ordinary TSX expressions read server-owned state and update automatically after an action; no repeated binding names or browser component runtime.

- [A complete site with shared defaults](/docs/reference/0.13.2/examples/static-site.md): Define metadata, layout, CSS, caching, and asset export once, then keep each page focused on its content.

- [JSON routing, broadcast, and binary frames](/docs/reference/0.13.2/examples/handlers.md): Text messages select a handler by type. Binary frames stay as Buffer values and can be accepted by the handler that understands them.

- [Bound admission, work, and slow peers](/docs/reference/0.13.2/examples/protected-route.md): Production controls are opt-in and route-local. Authenticate before upgrade, cap every queue, and use one heartbeat scheduler for the whole route.

- [Match handlers and resumable ownership](/docs/reference/0.13.2/examples/rooms-sessions.md): Give the match its own socket route, then dispatch join, move and resume by type. These canonical socket-starter handlers create and recover server-owned player sessions; they are not a room-broadcast or account-authentication example.

- [Fixed-step work without overlapping ticks](/docs/reference/0.13.2/examples/fixed-step.md): FixedStepService compensates for scheduler drift, bounds catch-up, contains async failures, and reports lag that was deliberately dropped.

- [Versioned envelopes and the dependency-free client](/docs/reference/0.13.2/examples/protocol.md): Negotiate a finite protocol version before upgrade, then share stable envelopes and error codes between server and client.

- [Bring your own broker adapter](/docs/reference/0.13.2/examples/distribution.md): Redweb supplies a bounded composition seam rather than choosing infrastructure. Events are finite, deduplicated briefly, and explicitly best-effort.

- [Readiness first, then bounded shutdown](/docs/reference/0.13.2/examples/draining.md): Stop placement to the node, flip readiness, let cooperative handlers observe cancellation, and await deterministic cleanup.

- [HttpServer](/docs/reference/0.13.2/api/httpserver.md): Wraps Express with sensible defaults (JSON body parsing, CORS, and static asset folders) and starts listening immediately unless `listen: false` is supplied. You get the underlying Express instance back via `app`.

- [BaseHttpServer](/docs/reference/0.13.2/api/basehttpserver.md): Public Express app builder used by HttpServer and HttpsServer. Use it for advanced composition when you want Redweb middleware, static files, and services without any listener behavior.

- [HttpsServer](/docs/reference/0.13.2/api/httpsserver.md): TLS-enabled variant of `HttpServer`. Accepts `ssl.key` and `ssl.cert` file paths, wraps them in an https server, and bootstraps the same middleware pipeline.

- [SocketServer](/docs/reference/0.13.2/api/socketserver.md): HTTP-upgrade WebSocket server on top of `ws`. Builds and listens on its own HTTP server by default; if you pass a Node `server`, it attaches upgrade handling and leaves `.listen()` to you unless `listen: true` is explicit.

- [SecureSocketServer](/docs/reference/0.13.2/api/securesocketserver.md): HTTPS + WebSocket pairing. Mirrors `SocketServer` but wraps an HTTPS server built from the provided TLS files.

- [SocketRoute](/docs/reference/0.13.2/api/socketroute.md): Defines a WebSocket endpoint and owns its handlers, services, clients, and opt-in multiplayer policies. Routes can add bounded admission, transport limits, ordered work, heartbeat, rooms, resumable sessions, distribution, draining, metrics, and protocol negotiation without changing legacy routes.

- [SocketService](/docs/reference/0.13.2/api/socketservice.md): Route-scoped background worker. Used by `SocketRoute` to run ticks or lifecycle hooks tied to a specific route.

- [FixedStepService](/docs/reference/0.13.2/api/fixedstepservice.md): Route-scoped simulation clock that compensates for drift, prevents overlapping async ticks, bounds catch-up work, and reports dropped retained lag instead of replaying forever.

- [RoomRegistry](/docs/reference/0.13.2/api/roomregistry.md): Bounded route-local connection groups. Sockets normally use joinRoom, leaveRoom, and roomBroadcast; disconnect cleanup removes all memberships and reclaims empty rooms.

- [SessionRegistry](/docs/reference/0.13.2/api/sessionregistry.md): Bounded, expiring ownership records for application-issued opaque session IDs. Redweb handles takeover and expiry; the application owns credential issuance and payload validation.

- [ProtocolClient](/docs/reference/0.13.2/api/protocolclient.md): Dependency-free helper from redweb/client for opt-in versioned routes. It builds, sends, and validates stable envelopes from the same checked-in schema used by server constants and TypeScript declarations.

- [SocketRegistry](/docs/reference/0.13.2/api/socketregistry.md): Small EventEmitter-backed list for socket-scoped entities (players, rooms, etc.). Emits `added` and `removed` events.

- [BaseHandler](/docs/reference/0.13.2/api/basehandler.md): Abstract message handler. Provide a name in the constructor; clients send `{ type: name, ... }` to target JSON messages, while binary frames can be accepted and handled as raw Buffer payloads.

- [sendJson](/docs/reference/0.13.2/api/sendjson.md): Utility to JSON.stringify data and send it over a `ws` socket.

- [ERROR_CODES](/docs/reference/0.13.2/api/errorcodes.md): Stable framework error codes shared by protocol-enabled servers and redweb/client.

- [SOCKET_OPTIONS](/docs/reference/0.13.2/api/socketoptions.md): Default WebSocket server options used by BaseSocketServer.

- [HTTP_OPTIONS](/docs/reference/0.13.2/api/httpoptions.md): Frozen defaults used by the HTTP and HTTPS server constructors.

- [ENCODINGS](/docs/reference/0.13.2/api/encodings.md): Supported request-body parser names for HTTP server configuration.

- [METHODS](/docs/reference/0.13.2/api/methods.md): Lowercase HTTP verb helpers passed straight to Express route registration.

- [BaseSocketServer](/docs/reference/0.13.2/api/basesocketserver.md): Shared lifecycle and route-composition base for SocketServer and SecureSocketServer. Extend the concrete servers for normal applications; use this type when building infrastructure integrations.

- [LiveHtmlServer](/docs/reference/0.13.2/api/livehtmlserver.md): Decorator-first server rendering and realtime browser updates on Redweb’s existing HTTP and WebSocket stack. Pages can be connection-scoped or intentionally shared.

- [LivePage and start](/docs/reference/0.13.2/api/livepage.md): A page is an ordinary decorated class; extending LivePage is optional. start() is the concise entry point that creates a LiveHtmlServer for one or more page classes.

- [page, component, state, action, view](/docs/reference/0.13.2/api/livedecorators.md): Small TypeScript decorators declare routes, reusable component ownership, reactive server state, browser-callable actions, and collection item views.

- [JSX rendering](/docs/reference/0.13.2/api/jsxruntime.md): Dependency-free server-side TSX that renders directly to HtmlFragment values. It provides readable components, fragments, arrays, automatic escaping, safe attributes, and existing html-fragment interoperability without React, a virtual DOM, or hydration.

- [html, attribute, url, each, codeBlock](/docs/reference/0.13.2/api/safehtml.md): Safe composition primitives escape text and quoted primitive attributes by default. URL attributes additionally reject executable, protocol-relative, and malformed values. Arrays must contain trusted HtmlFragment values.

- [defineSite](/docs/reference/0.13.2/api/definesite.md): Defines shared static-site CSS, metadata, caching, layout, canonical URLs, and export behavior once. Site pages are always runtime-free.

- [exportStatic](/docs/reference/0.13.2/api/exportstatic.md): Renders non-live decorated pages to deterministic directory indexes and content-addressed CSS. It is intended for docs, marketing pages, and static hosting.

- [HtmlRenderer](/docs/reference/0.13.2/api/htmlrenderer.md): Lower-level rendering utility behind Live HTML. Most applications should use page(), start(), defineSite(), and exportStatic(); this surface supports advanced integrations and tooling.

- [defineSocketContract](/docs/reference/0.13.2/api/socketcontract.md): One shared Standard Schema contract validates wire payloads and infers client/server types. Route URLs choose the service; individual handler factories dispatch by message type.

- [Complete public TypeScript declarations](/docs/reference/0.13.2/api-types.md): Exact shipped signatures, options, and public types; not standalone application snippets.