From db195ca91c2c140ca5f736b94270594fceb54caa Mon Sep 17 00:00:00 2001 From: Eduardo Gurgel Date: Fri, 22 May 2026 02:32:23 +1200 Subject: [PATCH] docs(realtime): alert about high-frequency updates using presence (#45502) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Clarify that presence should not be used for high-frequency updates Presence___Supabase_Docs ## Summary by CodeRabbit * **Documentation** * Added guidance on optimal use cases for Presence feature, clarifying it's best suited for slow-changing state and recommending Broadcast for high-frequency updates. Co-authored-by: Chris Chinchilla --- apps/docs/content/guides/realtime/presence.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apps/docs/content/guides/realtime/presence.mdx b/apps/docs/content/guides/realtime/presence.mdx index aa57aaaab14..a3403f5d6e3 100644 --- a/apps/docs/content/guides/realtime/presence.mdx +++ b/apps/docs/content/guides/realtime/presence.mdx @@ -20,6 +20,14 @@ When any client subscribes, disconnects, or updates their presence payload, Supa - **`join`** — a new client has started tracking presence - **`leave`** — a client has stopped tracking presence + + +Presence syncs state through the server and notifies **all** subscribers on every change. Calling `track()` rapidly — for example on every mouse move to share cursor positions — will flood the channel and cause performance problems. + +For high-frequency or fire-and-forget updates, use [Broadcast](/docs/guides/realtime/broadcast) instead. Presence is best suited for slow-changing state such as online/offline status, active document, or current page. + + + During a `sync` event, you may receive `join` and `leave` events simultaneously, even though no users are actually joining or leaving. This is expected behavior—Presence reconciles its local state with the server state, which can trigger these events as part of the synchronization process. This reflects state reconciliation, not real user movement.