Api Reference
Shared Connections
A page showing many live cards shouldn't need one independent connection for every component. PresenceKit provides a shared browser-tab connection manager.
import {
createPresenceConnectionManager,
getSharedPresenceClient,
} from "@iconical/presencekit";Default shared manager
getSharedPresenceClient() returns the same manager within a browser tab. Outside the browser it creates a fresh instance, avoiding a shared cross-request server singleton. React/Vue/Svelte adapters use this manager automatically.
const shared = getSharedPresenceClient();
const stop = shared.subscribePresence("123456789012345678", {
onUpdate(data) { console.log(data.presence?.status); },
onError(error) { console.error(error); },
});
// Later: stop();Dynamically change the roster
const manager = createPresenceConnectionManager();
const watcher = manager.watchPresences(
["123456789012345678"],
{ onUpdate(data) { console.log(Object.keys(data.presences)); } },
{ transport: "auto" },
);
watcher.setUserIds([
"123456789012345678",
"234567890123456789",
]);
// When the component/page is disposed:
watcher.unsubscribe();watchPresences() returns { setUserIds, unsubscribe }. The shared manager supports up to 250 distinct IDs per connection group, dividing network operations into batches of 25. Direct createPresenceClient().getPresences() and .subscribePresences() still accept at most 25 IDs each.
Inspect connectivity
const manager = getSharedPresenceClient();
console.log(manager.getDiagnostics());
const unsubscribeDiagnostics = manager.observeDiagnostics((diagnostics) => {
console.log(diagnostics.mode, diagnostics.users, diagnostics.activeConnections);
});
// Later: unsubscribeDiagnostics();ConnectionDiagnostics: { mode, activeConnections, subscribers, users, lastUpdateAt, lastError }. Modes: connecting, sse, poll, stopped.
For React use useConnectionDiagnostics(); for Vue use useConnectionDiagnostics(); for Svelte use createConnectionDiagnosticsStore().
How it shares
Subscribers using the same transport and polling interval can share network connections. Membership changes adjust the affected batches; cleanup removes unneeded subscriptions and data. Sharing is scoped to a JavaScript runtime/browser tab, not between every browser visitor.
Was this page helpful?