Quick Start

CloudBase JS SDK exposes Supabase-compatible realtime through app.realtime():

• Broadcast: low-latency messages on a channel, such as collaborative cursors or ephemeral signaling
• Presence: sync who is currently on a channel
• Postgres CDC: listen to INSERT / UPDATE / DELETE on PostgreSQL tables

The capability is available after you import the full @cloudbase/js-sdk. The same app instance reuses one Realtime client. Use app.realtime() in the browser, Node.js, and WeChat mini programs.

Difference from document-database watch()

collection.watch() listens to document database collection changes and belongs to @cloudbase/js-sdk/realtime (registerRealtime). app.realtime() provides Broadcast / Presence / PostgreSQL CDC and belongs to @cloudbase/js-sdk/realtime-js (registerRealtimeJs). They are not interchangeable. For document-database listeners, see watch().

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id",
  accessKey: "your-publishable-key",
});

const realtime = app.realtime();
const channel = realtime.channel("room");

channel.on("broadcast", { event: "cursor-pos" }, (payload) => {
  console.log(payload);
});

channel.subscribe((status, err) => {
  if (status === "SUBSCRIBED") {
    console.log("subscribed");
  }
  if (status === "CHANNEL_ERROR" || status === "TIMED_OUT") {
    console.error(status, err);
  }
});

After SUBSCRIBED, you can send() or track(). Always clean up channels when you are done, to avoid leaking connections:

await channel.unsubscribe();
await realtime.removeChannel(channel);

// Or tear everything down and disconnect
await realtime.removeAllChannels();

Environment	Notes
Web	Call app.realtime() after the full SDK import
Node.js	Install the optional ws dependency; Cloud Functions / CloudBase Run pick up credentials automatically
WeChat mini program	Always use app.realtime(); do not new RealtimeClient(). The base library must support wx.connectSocket

CloudBase enables dual-connection hot-cut around 270s by default, to stay under the gateway max connection lifetime. Environments without window.Worker (such as mini programs) do not start the Worker heartbeat. Sign-in, token refresh, and sign-out are synced to Realtime automatically; you usually do not need to call setAuth() yourself.

Capabilities

Capability	Listen type	Typical use
Broadcast	broadcast	Collaborative cursors, signaling, room messages
Presence	presence	Who is online, join / leave
Postgres CDC	postgres_changes	Live refresh of PostgreSQL table data

Install and register

The full SDK already registers Realtime. Call app.realtime() directly.

On-demand imports treat document-database watch() and app.realtime() as two modules. Do not mix them up:

import cloudbase from "@cloudbase/js-sdk/app";
import { registerAuth } from "@cloudbase/js-sdk/auth";
// Document-database watch(), optional
import { registerDatabase } from "@cloudbase/js-sdk/database";
import { registerRealtime } from "@cloudbase/js-sdk/realtime";
// Broadcast / Presence / Postgres CDC
import { registerRealtimeJs } from "@cloudbase/js-sdk/realtime-js";

registerAuth(cloudbase);
registerDatabase(cloudbase);
registerRealtime(cloudbase);
registerRealtimeJs(cloudbase);

const app = cloudbase.init({ env: "your-env-id" });
const realtime = app.realtime();

Module	Package	Register function	Use
Document realtime	@cloudbase/js-sdk/realtime	registerRealtime	collection.watch()
Realtime	@cloudbase/js-sdk/realtime-js	registerRealtimeJs	app.realtime()

Note

Node.js realtime requires the optional ws package. In WeChat mini programs, always use app.realtime() and do not new RealtimeClient(), so the host can reuse the registered wsClass / reqClass adapters.