A real-time collaborative document editor (a small Google Docs). Several logged-in users edit the same rich-text document at once and see each other's changes live, with owner / editor / viewer permissions enforced on the server.
Live: https://collab-docs-client-40sw.onrender.com
Open the live link in two different browsers (or one normal and one private window) and log in as two demo users. They share a welcome document with things to try.
| User | Password | Role on the welcome document | |
|---|---|---|---|
| Alice | [email protected] |
try-collab-docs |
owner: edit, share, rename, delete |
| Bob | [email protected] |
try-collab-docs |
editor: edit, rename |
| Carol | [email protected] |
try-collab-docs |
viewer: read only |
You can also register your own account and share documents by email.
Hosted on Render's free tier: after 15 idle minutes the servers sleep, so the first visit can take about a minute. The demo accounts are public, so the welcome document may have been edited by others.
- Accounts with hashed passwords and token-based sessions
- Create, rename, share, and delete documents
- Rich text: bold, italic, headings, lists, undo/redo
- Live collaboration: everyone sees changes as they happen, and simultaneous edits merge
- Keep typing while offline; changes sync when the connection returns
- Editor and viewer roles, enforced on the server
- Removing someone's access takes effect immediately, even while they have the document open
- "Anyone with the link" sharing: the owner can let people without an account view or edit a document
flowchart LR
Browser["Browser<br/>React + Tiptap + Yjs"]
Browser -- "HTTPS" --> API["server/<br/>Express REST API"]
Browser <-- "WebSocket" --> COL["collab/<br/>Hocuspocus server"]
API --> DB[("PostgreSQL")]
COL --> DB
| Part | Job |
|---|---|
client/ (React + Vite) |
The UI and the editor |
server/ (Express) |
Accounts, the document list, renaming, sharing, deleting |
collab/ (Hocuspocus) |
The live content of open documents, over a WebSocket |
| PostgreSQL | Users, documents and their content, and who has which role |
- Permissions: every request and every live connection is checked against the database by the server that receives it. Nothing the browser says is trusted.
- Live editing: each browser keeps its own copy of the document. Changes are sent as small updates through the collab server to everyone else, and Yjs merges them so every copy ends up identical.
- Saving: the collab server saves open documents to PostgreSQL shortly after changes and when the last person leaves, and loads them from there when they are opened.
- Yjs for real-time sync. Sending the whole document on every change would let simultaneous edits overwrite each other. Yjs is a proven CRDT: it merges edits from any number of people, in any order, and supports offline editing.
- PostgreSQL. The data is relational (users, documents, and who can access what), and the database enforces the rules: unique emails, valid roles, and documents that are never left without an owner.
- Two servers. Short HTTP requests and long-lived live connections are different workloads, so each runs, restarts, and scales on its own. Both share one database.
- Link sharing. The link is the document's random ID, so it works like a password: whoever has it gets the level the owner chose (view or edit), without an account. They can never rename, share, or delete, the number of visitors per document is capped, and changing the setting disconnects them immediately.
- Documents you can't access return "not found". This way nobody can discover whether a document exists by guessing its address.
- API: it keeps no state between requests, so more copies can run behind a load balancer.
- Collab server: everyone editing one document must reach the same server. Route all connections for a document to one instance, or let instances share updates through Redis.
| Suite | Tool | Tests |
|---|---|---|
| API | Vitest | 101 |
| Collab server | Vitest | 73 |
| Browser (Chrome, Firefox, WebKit) | Playwright | 24 |
The tests cover accounts, permissions, live sync between several users, offline edits, saving and reloading, server restarts, and what happens when the database is down. All suites run in GitHub Actions on every push. Local load tests are in loadtest/.
- Passwords are hashed with bcrypt and never stored or logged in plain text
- Every request and live connection is authenticated and checked for permission on the server
- SQL queries are parameterized; the API only accepts requests from the app's own site
- Error messages to users are generic; details stay in the server logs
- Login attempts are rate limited
- Link visitors are limited to what the owner allows, and can never rename, share, or delete
Prerequisites: Node.js 22 or newer, and PostgreSQL 13 or newer.
- Create two databases, one for development and one that tests may wipe:
psql -U postgres -c "CREATE DATABASE collab_docs;" psql -U postgres -c "CREATE DATABASE collab_docs_test;" - Copy
server/.env.exampletoserver/.envandcollab/.env.exampletocollab/.env, then fill in your database password and the same long randomJWT_SECRETin both:node -e "console.log(require('crypto').randomBytes(48).toString('hex'))" - Install, create the tables, and add the demo users:
cd server && npm install && npm run db:init cd ../collab && npm install && npm run seed:demo cd ../client && npm install - Start each in its own terminal:
npm run devinserver/,collab/, andclient/. Open http://localhost:5173.
Tests: npm test in server/ and in collab/. For the browser tests (after step 3):
cd e2e && npm install && npx playwright install && npx playwright test.
client/ React + Vite app
server/ Express REST API and the database schema
collab/ Hocuspocus server and the demo data
e2e/ Playwright browser tests and the demo GIF recorder
loadtest/ Local load tests
render.yaml Deployment configuration for Render
Deployed on Render from render.yaml: a PostgreSQL database, the two servers, and the client as a static site. Secrets are set in the Render dashboard and never committed.
- One instance of each server
- Sessions last an hour; after that you log in again
- No password reset, email verification, or account deletion
- No version history, other users' cursors, or comments. With an edit link, anyone who has the link can erase a document and there is no way to undo it
