Realtime subscriptions

Create a client pointed at your PocketBase server and authenticate the user before subscribing to protected records:

import PocketBase from "pocketbase";

const pb = new PocketBase("http://127.0.0.1:8090");
await pb.collection("users").authWithPassword(
  "person@example.com",
  "password-from-user",
);

The client has a valid auth token. Public collection rules may allow an unauthenticated subscription, but protected rules require this step.

Subscribe to all events that the collection rule permits:

const unsubscribe = await pb.collection("messages").subscribe("*", (event) => {
  console.log(event.action, event.record.id);
});

The callback receives a record event. The action identifies the change, and the record contains the affected data that the request is authorized to see.

Use a record identifier when a screen needs updates for one entity:

const stopOrder = await pb.collection("orders").subscribe(
  "ORDER_RECORD_ID",
  (event) => console.log(event.action, event.record),
);

The callback runs when the selected record changes and the current authorization permits the event.

Call the function returned by the subscription when the component or screen is disposed:

await unsubscribe();
await stopOrder();

The client stops listening for those subscriptions. Do this before replacing a view to avoid stale callbacks and duplicate updates.

Handle the client's connection error or close signal by showing a reconnect state, refreshing authentication if its token is no longer valid, and establishing the subscription again after the connection returns.

async function reconnect() {
  if (!pb.authStore.isValid) {
    await pb.collection("users").authWithPassword(
      "person@example.com",
      "password-from-user",
    );
  }
  return pb.collection("messages").subscribe("*", onMessage);
}

Use backoff in production and remove the previous unsubscribe function before installing a replacement. Do not assume events missed while disconnected are replayed; refetch the relevant records after reconnecting and then resume the subscription.