How-to guides

Task-oriented recipes — each solves one problem and assumes you know the basics. If you don't, start with the Tutorials for a guaranteed-success build, then come back here to get a specific thing done.

Contract & interactions

The three wire patterns declared on one contract, plus the cross-node bus.

• Requests — typed request/response calls with validated inputs and results.
• Events & rooms — push server events to a client, a room, or everyone.
• Topics — let clients subscribe to server-owned streams and authorize each subscribe.
• Cluster event bus — server.publish/server.subscribe across nodes with local echo.

Transports

The pluggable client↔server wire. Pick one, then wire it on both ends.

• Choose a transport — decide between WebSocket, HTTP, libp2p, and loopback.
• WebSocket transport — the default duplex transport for server and client.
• HTTP transport — SSE plus long-poll where a socket won't do.
• libp2p transport — bring your own libp2p node for peer-to-peer reach.
• Loopback transport — in-memory client↔server for fast tests.

Authentication

Prove who's on a connection — the connect-time primitive, or the batteries-included plugin.

• Choose an auth strategy — hand-rolled authenticate vs. @super-line/plugin-auth.
• Authenticate & assign roles — freeze a role at connect with authenticate(handshake).
• Add authentication (plugin) — first-party identity, sessions, roles, keys, and JWT in three touch-points.
• Sessions, roles & API keys — durable sessions, roles-as-data, and slp_ service keys.
• JWT & sealed tokens — server-minted bearer assertions for stateless and cross-service connect.
• Server-side hooks — before/after connection admission, provisioning policy, and audit.
• Provision an agent identity — run an AI agent as an ordinary API-key user.
• Reset a password — logged-out recovery through a host callback.

Collections

Where typed collection state lives, and how it reaches other nodes.

• Choose a collection backend — match a row and CRDT backend to your durability and clustering needs.

Queues & workers

• Add a queue (plugin) — wire @super-line/plugin-queue into one contract and one server.
• Enqueue and observe jobs — create jobs from a request handler and expose safe summaries to a browser.
• Schedule periodic jobs — run cron schedules with timezones, catch-up, and overlap policy.
• Run queues across a cluster — use durable cluster-wide concurrency, leases, and stable node keys.

Server

Authorize, extend, and observe the server-authoritative core.

• Connection env — vend typed, server-owned per-connection state the client reads live.
• Chat backbone — add channels, membership control, and messages via @super-line/plugin-chat.
• Plugin-chat 0.5 migration — move from assembled feeds and bot helpers to durable per-message parts and host-owned automation policy.
• Migrate to the one React binding — Register moved to @super-line/react, plugin-auth/react shrank to the session owner, chat auto-builds its client, useRequest unified.
• Chat streaming — store an agent's whole turn as typed parts that stream live and survive reloads.
• Chat bots — run an LLM as a regular authenticated user over its own connection.
• Chat resources — attach your CRDT documents to channels with membership-gated access.
• Chat headless — drive a channel from scripts over a stdin/stdout line protocol.
• Middleware & lifecycle — hook connect, disconnect, and per-message handling.
• Errors — throw and handle SuperLineError across the wire.
• Introspection & presence — inspect topology, connections, and who's online.
• Composition — assemble a contract from surfaces with defineSurface/mergeSurfaces.
• Building plugins — ship a paired contract-fragment plus runtime bundle.

Client

Consume the contract from the browser or Node.

• React — bind requests, events, topics, and collections with createSuperLineHooks.
• Serialization — control how payloads cross the wire.

Scaling

Fan out across nodes with a pluggable server↔server adapter.

• Choose an adapter — match a fan-out backend to your deployment.
• Redis adapter — pub/sub fan-out over Redis.
• libp2p adapter — broker-less gossip fan-out.
• RabbitMQ adapter — fan-out over a RabbitMQ broker.
• ZeroMQ adapter — fan-out over ZeroMQ sockets.

Tooling & workflow

Develop, test, and operate super-line.

• Control Center — inspect topology and live message traffic in the browser.
• DevTools panel — debug one tab's client: in-flight requests, reconnect backoff, per-subscription routing, CRDT contents.
• Testing — drive contracts end to end with the loopback transport.
• AI agents — wire agents as first-class server-authoritative writers.

Want the model behind these recipes rather than the steps? See Concepts. Every export is catalogued in the API reference.