From 25f9f7c5e341ec431c1929d35dccc0bbe2eec977 Mon Sep 17 00:00:00 2001 From: Jonathan Fulton Date: Thu, 19 Feb 2026 03:08:08 -0500 Subject: [PATCH] docs(realtime): add note about sync event behavior in Presence (#42338) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What kind of change does this PR introduce? Documentation improvement for Realtime Presence. ## What is the current behavior? The Presence documentation doesn't explain that during a `sync` event, clients may receive `join` and `leave` events simultaneously even when no users are actually joining or leaving. This can be confusing for developers new to Presence. ## What is the new behavior? Added an explanatory note clarifying that: - During `sync`, you may receive `join` and `leave` events at the same time - This is normal and expected - It reflects state reconciliation with the server, not real user movement This helps developers understand this behavior upfront rather than having to discover it through debugging. ## Additional context As mentioned in the issue, this behavior is discussed in [this community discussion](https://github.com/orgs/supabase/discussions/26748) where the solution had to be discovered by users. Fixes #41175 ## Summary by CodeRabbit * **Documentation** * Clarified behavior during sync events in the Realtime Presence guide. Added explanation that simultaneous join and leave events may occur due to state reconciliation rather than actual user movement changes. ✏️ Tip: You can customize this high-level summary in your review settings. --- apps/docs/content/guides/realtime/presence.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/apps/docs/content/guides/realtime/presence.mdx b/apps/docs/content/guides/realtime/presence.mdx index dae2120972f..972446f8850 100644 --- a/apps/docs/content/guides/realtime/presence.mdx +++ b/apps/docs/content/guides/realtime/presence.mdx @@ -20,6 +20,12 @@ 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 + + +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. + + + The complete presence state returned by `presenceState()` looks like this: ```json