Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Two People, One Document: Real-Time Collaborative Editing in Your Vibe Project

Sync is just the pipe — collaborative editing is a set of rules: three permission levels, visible cursors, conflict handling that never silently loses words, offline safety, and version history, with a worked funnel.

Two people sitting side by side, looking at a laptop screen together while one points at it (real photo)

One thing up front: this guide is only about real-time collaborative editing itself — what happens when two people change the same document at the same time: cursors, permissions, conflicts, dropped connections, and version history. Comments and @-mentions belong to the earlier guide on comment systems, mentioned here only where permissions touch them; share links and public access have their own guide too. The example product in this article, “Spruce Docs” (an online collaborative document tool), and the people in it, “Xiao Man” and “A Zhe”, are fictional examples used to make the points concrete — not a real product or real users.

Many vibe projects add collaborative editing starting from a romantic picture: two people open the same document and cursors dance across the screen like in a movie. The author spends a weekend wiring up real-time sync, ships it, and then discovers almost nobody actually uses it together. Worse, a user complains in the group chat: the paragraph I worked on all morning was overwritten by a colleague. The problem is not the sync itself. The author built “syncing” but not the whole set of things collaborative editing really needs: who can come in, what happens when two people change the same line, what happens when the connection drops, and how to go back when something goes wrong. Sync is just the pipe. Collaborative editing is a set of rules. With the pipe open and no rules in place, two people using it together only makes a bigger mess than one person alone.

1. What collaborative editing actually is: three things to keep apart

Before building, separate three ideas that are easy to mix up. First, “online at the same time”: two people have the same document open. That is a state, not a feature. Second, “real-time sync”: one person types and the other person’s screen shows it immediately. That is just the pipe. Third, “collaborative editing”: when two people change the same content, the system guarantees the final result is one both of them can accept, nothing gets lost, and mistakes can be undone. The first two only make a demo. The third is what makes it a feature. Many vibe projects stop at step two because step three looks fiddly: overlapping cursors, permissions, conflicts, dropped connections, versions. None of them is hard on its own, but missing any one of them means users will hit it in real use.

Whether your product needs collaborative editing should not start from “everyone else has it”. Write down one sentence first: “Two people changing the same thing at the same time saves the user from repeating which task?” If two people take turns editing a plan and have to shout in the group chat “are you done yet?”, collaborative editing saves the back-and-forth of sending files around, and it is worth building. If your product is a personal ledger or a diary, a scenario where two people edit the same thing barely exists — adding it only adds buttons nobody clicks and bugs nobody fixes. Scenario first, feature second. Do not reverse that order.

2. Who can come in and do what: permissions come before sync

The first gate of collaborative editing is not technical, it is permissions. The moment a document is shared, the first question is: what can the person coming in do? At minimum, three levels: view only, comment, and edit. A view-only person should not have a cursor in the document, and the edit buttons in their toolbar should be greyed out; a commenter can leave notes in the margin but cannot touch the text; only an editor can actually change the text. Beyond the three levels, there is also a default: what level does someone get when they come in through a link? Defaulting to “can edit” is the most dangerous option — like taping the house key to the front door. Defaulting to “view only” and letting people ask for edit access is far less trouble.

Permissions also need to be taken back. Invite links should expire, and when a colleague leaves or a contractor finishes, their access should be revoked with one click — not by digging through record after record. One more practical point: a permission change has to take effect immediately. If someone is editing when their permission is revoked, their screen should say right away, “Your edit permission has been revoked”, instead of letting them type for half an hour and only discovering on save that everything was wasted. Permissions are the foundation of collaborative editing. If the foundation is not solid, nothing built on top of it matters.

// Permission check: run it before every write, don't just hide buttons
function canEdit(user, doc) {
  if (doc.ownerId === user.id) return true;
  const grant = doc.grants.find(g => g.userId === user.id);
  if (!grant) return false;
  if (grant.expiresAt && grant.expiresAt < Date.now()) return false;
  return grant.role === 'editor';
}
// Hiding buttons in the UI is only experience; without a server-side
// check, there is no protection at all.

One detail that is easy to miss: the document owner belongs inside the permission system too. What happens when ownership is transferred, the owner’s account is closed, or the owner stops logging in? A small project can start with one simple rule: the owner can transfer ownership to any editor, and the original owner automatically becomes an editor afterwards. A simple rule is fine — what matters is writing it down and making it visible in the interface, instead of improvising when something goes wrong.

3. Cursors, selections, and “who is looking”: make each other visible

The most useful part of collaborative editing is often not the sync itself, but “seeing each other”. Each person gets a coloured cursor with their name next to it, and when someone selects a passage the other person sees the selection change colour. Put those three things together and users finally feel safe editing at the same time. Without them, two people are feeling around in the dark: you do not know which paragraph the other person is editing, and sooner or later you collide. Cursor sync does not need to be very fast — a few times a second is enough, and faster only wastes bandwidth — but a cursor has to disappear promptly. If someone closed the page more than ten seconds ago, their cursor should be gone from the screen, or users will think someone is still editing there and hold back.

“Who is looking” also needs to be shown differently depending on the case. Read-only people should appear in the online list too, but with a small “read-only” mark next to their avatar — otherwise editors will assume they are also editing and avoid touching their own paragraph. The online list should also show when each person was last active: active three minutes ago and opened three hours ago and forgot to close are two different things. The first means “they will see your change right away”; the second means “they just left the page open”. Telling those apart saves a lot of unnecessary waiting and misunderstanding.

// Presence: only sync "where the person is", not "what they wrote"
broadcast({
  type: 'presence',
  userId: 'xiao-man',
  userName: 'Xiao Man',
  color: '#FE4A16',
  cursor: { line: 12, column: 5 },
  selection: { from: 120, to: 145 },
  role: 'editor',          // read-only people broadcast too, marked "read-only"
  lastActiveAt: Date.now()
});
// When presence arrives, update only the cursor layer, never the
// document content — keep the two channels separate.

4. Two people change the same line: conflict handling is the core

This is the hardest section of collaborative editing, and the easiest to underestimate. When two people change the same line at the same time, the system must produce one definite result — and that result must not lose anything. The crudest approach is “last writer wins”: whoever saves last overwrites the other person. That works fine for one person, but in a collaborative setting it is a disaster — Xiao Man’s morning of writing disappears because A Zhe fixed a typo and hit save. Users will not forgive that kind of loss, even if it happens only once.

A better approach merges by operation instead of overwriting the whole text. If two people changed different paragraphs, keep both; if they changed the same line, keep both changes and mark them so the users can choose. Getting this far does not need advanced algorithms — it needs an attitude: the system must never quietly throw away something a user wrote. After any automatic merge, leave a trace in the interface: “A Zhe changed line 12 while Xiao Man changed the same line; both versions are kept, click here to compare.” Only when users see that trace will they trust that the system did not silently eat their words.

The rigorous way to do this is to use a mature approach such as operational transformation or conflict-free replicated data types, which let two people’s edits merge correctly by construction instead of being patched up afterwards. For a vibe project, there is no need to implement these algorithms from scratch — using an existing collaborative editing library is the right call. Spend your energy on permissions, prompts, and version history, not on building a sync engine. When choosing a library, check only three things: can it resume automatically after a dropped connection, will two people changing the same line lose text, and does it ship cursor sync out of the box? If it passes all three, start building; a library that fails any of them is not worth using, however lightweight it is.

There is another kind of conflict that is not technical at all, but human: two people disagree about the same sentence, one changes it, the other changes it back, and they tug back and forth. What the system can do here is keep a clear record — who changed which sentence and when — so the two people can discuss the actual edit instead of accusing each other in the group chat of “touching my stuff again”. A change log is not there to assign blame; it is there so collaboration has something to point at.

5. After the network drops, a refresh, or a disconnect: never lose a word

The thing collaborative editing users fear most is not slowness, it is losing words. In the seconds when the network is down, the user keeps typing, and the system must store those words locally first, then send them when the connection comes back. While they cannot be sent, the interface has to say so plainly: “You are offline. Your changes are saved locally and will sync when you are back online.” Users can accept “it cannot sync right now”; they cannot accept “I thought it synced, but it did not”.

Refreshing the page works the same way. If a user accidentally hits refresh, the document they come back to should look like the last thing they saw, and the words they had not sent yet should still be there — not rolled back to the last saved state. Doing this needs local caching plus server-side version numbers: every sync carries a version number, the local copy stores “synced up to version N” and “changes not yet sent”, and after a refresh the local copy is restored first, then checked against the server version, with mismatches flagged for the user to confirm. It sounds fiddly, but it is the baseline of collaborative editing: under no circumstances may words a user wrote quietly disappear.

One more detail for reconnection: when the connection comes back, do not immediately push the locally queued changes out in one burst. First look at the newest server version. If the other person changed a lot while you were away, the system should pull their changes down first, then merge the local changes on top, and tell the user: “While you were offline, A Zhe changed three places; they have been merged.” Pull first, then push — that order prevents most reconnection accidents.

6. Version history and “back to yesterday”: leave a way to regret

Once several people edit together, the chance of a wrong edit rises fast. Version history is the undo button for everyone: every substantial change automatically saves a version, the version list says who changed what and when, a user clicks once to see that version in full, and clicks again to restore it. When restoring, do not overwrite the current version directly — record the restore itself as a new version, so even a mistaken restore can be restored back. The undo pill can be taken, but the bottle must not be smashed.

How long versions are kept and how many are stored should be decided up front. A small project can set a rule like this: keep versions from the last 30 days, at most one automatic version per day, plus any versions the user names by hand. Named versions matter: before a release, before a review, before showing a client, save a version called “the version sent to the client” by hand, and never let automatic cleanup delete it. Put the rule in the help docs and in a corner of the version history page, so users can find it at a glance when they need it.

Comparing versions also has to be visual. Between two versions, mark the changes with colour: added words in green, deleted words in red, reordered paragraphs flagged. Handing a user two version numbers and asking them to guess what changed is the same as having no version history at all. The comparison view is where version history actually becomes useful, and it is worth the time to do well.

7. A fictional sample: from shared to truly edited together

The numbers below are a fictional sample, used to make the gap between “shared” and “truly edited together” concrete. Suppose “Spruce Docs” has 1,000 shared documents. Looking back after 7 days: 640 were opened by a collaborator, 410 were actually edited by two or more people, 328 merged without any conflict prompt, and 214 were still actively used by two people in the following week. Overall, out of 1,000 shared documents, only 214 (21.4%) became ongoing collaborative documents.

Collaborative editing conversion funnel: of 1,000 shared documents, 640 were opened by a collaborator, 410 were edited by two or more people, 328 merged without a conflict prompt, and 214 became ongoing collaborative documents (fictional sample)

The most revealing step is from the second to the third: 640 were opened, but only 410 had anyone actually write in them — 230 dropped off in between. People often open a document, glance at it, and leave, and the reason is usually not that the feature is bad: the permission was wrong (view-only when they wanted to edit), the entry point was too deep (three clicks from an email to reach the document), or the other person was not online and they did not know where to start with an empty document. Every drop in the funnel has a concrete cause, and fixes should be made one by one: fix the wrong default permission, move the entry point somewhere visible, add a “notify me when they come online” nudge. A funnel is not for showing off numbers; it is for locating what needs fixing.

Two other numbers are worth noting. Of the 410 documents that were actually edited, 82 showed a conflict prompt during merging (410 minus 328) — in other words, one in five genuinely collaborative documents hit a conflict. Conflict is not an edge case; it is a daily event in collaborative editing. That is why the conflict handling in section 4 is not a “just in case” feature but a “used every week” one, worth top priority. And of the 328 documents that merged smoothly, only 214 stayed in ongoing use — the 114 in between were mostly one-off collaborations: reviewed, fixed, done. That is normal. Not every collaboration has to become a long-term relationship; what the product should do is make one-off collaboration smooth too, instead of insisting every document become a long-term project.

8. Pre-launch checklist

Finally, a checklist you can tick off directly. Permissions: are the three levels clearly separated, is the default “view only”, does revoking a permission take effect immediately, do invite links expire? Presence: do cursors carry names, are read-only people marked, do cursors disappear after ten seconds of inactivity? Conflicts: will two people changing the same line lose words, is there a trace after a merge, can the change log be found? Dropped connections: are offline keystrokes stored locally, is it pull-then-push on reconnect, do words survive a refresh? Versions: how many days are automatic versions kept, will named versions survive cleanup, is a restore recorded as a new version, is the comparison view clear?

Three more things that are easy to miss. First, guide the first collaboration: when two people enter a document together for the first time, show a light prompt — “Xiao Man is here too, you can edit together” — which works better than ten pages of help docs. Second, export: a collaborative document should export with one click, so if a user ever leaves, they take the complete document with them, not a pile of sync records. Third, data boundaries: deleting, transferring, or archiving a document belongs only to the owner; when a collaborator clicks delete, it should only remove their own access, not delete someone else’s document. All three are small things, but they are all walls users will hit in real use.

The sign that collaborative editing is done well is not how smoothly the cursors glide. It is that after two people have used it for a month, nobody has lost a word, nobody has been silently kicked out, and nobody has argued over a wrong edit they could not undo. Get those three things right, and users will treat collaborative editing as an everyday tool instead of a demo showpiece.

Views 5Comments 0

Comments (0)

ME
0/1000
Loading comments...
Browse projectsPublish your project

Related articles

Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding
Real photo: a laptop, tablet, and phone on a wooden table showing the same green-leaf website, the phone view with navigation in one column, a potted plant nearby
Guide
Squashed on phones? Responsive layout and media queries, explained plainly

One page should stand up on a phone, a tablet, and a computer. This guide follows MDN's Responsive web design, Using media queries, and the viewport meta reference: fluid HTML, the viewport tag, fluid grids and max-width, images that never burst their container, media query syntax, breakpoints set by content, mobile first, responsive type, testing capability instead of width, and a pre-launch checklist.

Mobile AppsDesign ExperienceFrontend Engineering