Realtime

OpenCloud Realtime is a private broadcast API for refresh signals and transient coordination. PostgreSQL remains the durable source of truth.

const unsubscribe = await opencloud.realtime.subscribe(
  "items",
  ({ event, payload }) => {
    if (event === "changed") void reloadItems(payload);
  },
);

await opencloud.realtime.publish("items", "changed", {
  id: itemId,
});

subscribe(topic, handler) joins the app-qualified private topic and returns a synchronous unsubscribe function. publish(topic, event, payload) reuses an active subscription or creates a bounded connection when needed.

The SDK owns the WebSocket URL, app-qualified topic, user token, join envelope, heartbeat, reconnect, and session refresh. Topic names begin with a lowercase letter and contain lowercase letters, numbers, or hyphens. Event names are bounded identifiers.

Call unsubscribe() when the view unmounts and opencloud.dispose() when the app tears down. Send identifiers rather than secrets or full records. Do not open the Realtime socket, construct Phoenix messages, or use channel-style protocol APIs yourself.

On a custom domain, OpenCloud rechecks access for existing connections. Revocation or domain removal closes a socket within 25 seconds, or earlier when its current authorization expires. The SDK handles session refresh and reconnection while access remains valid; SDK 2.3.0 also recovers from channel close/error messages. Do not rely on an uninterrupted connection or use Realtime delivery as proof that a database write succeeded. Refresh durable data independently of Realtime and keep primary actions usable if it fails.

Use the custom-domain sign-out action and reload after success to clear the current page's SDK session and sockets.

Realtime ​

Realtime