Real-time sync patterns

Patterns for sync, presence, collaborative editing, and other live-updating features.

Convex makes basic real-time sync free — every useQuery is a subscription. Some features need more than basic sync: presence, optimistic updates, collaborative editing. The patterns:

Pattern: presence

“Show who’s currently viewing this document.”

convex/schema.ts

presence: defineTable({
  documentId: v.id("documents"),
  userId:     v.id("users"),
  lastSeen:   v.number(),
}).index("by_document", ["documentId"])

convex/presence.ts

export const heartbeat = mutation({
  args: { documentId: v.id("documents") },
  handler: async (ctx, { documentId }) => {
    const u = await ctx.auth.getUserIdentity();
    if (!u) return;
    const existing = await ctx.db
      .query("presence")
      .withIndex("by_document", q => q.eq("documentId", documentId))
      .filter(q => q.eq(q.field("userId"), u.subject))
      .unique();
    if (existing) {
      await ctx.db.patch(existing._id, { lastSeen: Date.now() });
    } else {
      await ctx.db.insert("presence", {
        documentId, userId: u.subject as Id<"users">, lastSeen: Date.now(),
      });
    }
  },
});

export const list = query({
  args: { documentId: v.id("documents") },
  handler: async (ctx, { documentId }) => {
    const cutoff = Date.now() - 30_000;
    const all = await ctx.db.query("presence")
      .withIndex("by_document", q => q.eq("documentId", documentId))
      .collect();
    return all.filter(p => p.lastSeen > cutoff);
  },
});

Client calls heartbeat every 10 seconds; list shows who’s active in the last 30s.

A scheduled function cleans up stale rows nightly.

Pattern: collaborative editing

Two approaches:

Operational transformation (OT)

Each edit is a transform. Server reconciles concurrent edits. Complex; use a library (Yjs, Automerge).

Last-write-wins per field

Each field is updated independently; last write wins. Simple; works for forms and structured docs.

For most apps, the second approach is enough. For Google-Docs-class collaborative text editing, integrate Yjs with a Convex sync provider.

Pattern: live cursors

Same shape as presence, but adds cursor: { x, y } updated on mousemove (debounced to 30 fps).

Pattern: notifications stream

A notifications table indexed by_user_and_read. Component subscribes via useQuery for the unread set. Reactive sync delivers new notifications instantly.

Limits

• ~10,000 concurrent subscribers per query (soft).
• Per-document presence with 1000+ users requires sharding or a different store.

Tips

Don’t store cursor positions in your main table. Put them in a separate cursors table; cleanup is much easier.

Start without OT. Most “collaboration” features (comments, presence, simultaneous form editing on different fields) work fine without OT.

Related

Real-time sync

The basics.

Real-time chat recipe

A worked example.

Multiplayer game recipe

Heavier real-time use.