Collaborative Editor
Collaborate on documents in real-time with others.
ReactTypeScriptNext.jsyjsTipTapProsemirrorCRDTTanstack-QueryShadcn UIMdxWebsocketsTailwind CSSSupabase
View Mode:
1. Problem Statement
What?
Maintaining data consistency in real-time collaborative environments is notoriously difficult due to race conditions and network lag.
Who?
Content creators and documentation teams needing a high-performance, conflict-free editing experience.
Why it mattered?
Standard database-per-keystroke models scale poorly and cause frequent merge conflicts in multi-user sessions.
2. Product Thinking
The Solution
Implemented a real-time collaborative editor using Tiptap and Yjs. The system synchronizes binary CRDT updates over WebSockets for awareness and conflict resolution. Approved content is converted from Prosemirror JSON to MDX, stored in Supabase, and pushed to GitHub via API to trigger automated Vercel deployments.
Alternatives Considered
- •Operational Transformation (OT) like Google Docs (high server complexity)
- •Simple locking mechanism (detrimental to collaborative flow)
- •Interval polling with diff-match-patch (high latency and conflict-prone)
Trade-offs Made
- •Binary CRDTs over JSON: Significant reduction in WebSocket payload size and memory overhead, though more complex to debug.
- •Admin Review Flow: Sacrificed instant site updates for a controlled GitHub API push, ensuring content quality before Vercel deployment.
- •Supabase Persistent State: Used as a 'hot' buffer for document drafts before they are matured into static MDX files.
3. System Architecture
Next.js + Tiptap
Frontend
Yjs WebSocket
Backend
API Gateway
Backend
Postgres DB
Database
GitHub API
External
Node FS / Vercel
Database
Frontend
Backend
Database
Hover over components to see details. This diagram is interactive.
4. Impact & Outcome
Summary
Engineered a production-ready collaborative document editor featuring real-time sync, presence awareness, and an automated MDX publishing pipeline.
Key Impact
- ✓Enabled sub-100ms synchronization for concurrent editors.
- ✓Automated the documentation lifecycle from rich-text editing to static site deployment.
- ✓Reduced manual content publishing overhead by 90% via GitHub API integration.
Outcome
The tool serves as the primary contribution engine for ExplainBytes, allowing the community to safely propose and refine technical documentation.
5. Challenges & Failures
What Broke
Converting complex Prosemirror nodes (tables, code blocks) to clean MDX was prone to formatting errors.
Lesson Learned
Built a custom recursive visitor pattern to map Prosemirror JSON nodes to MDXAST (Markdown AST) for reliable serialization.
What Broke
High-frequency awareness updates (cursor movements) saturated the WebSocket connection during 10+ user sessions.
Lesson Learned
Implemented update throttling (150ms) and delta-based awareness broadcasts to reduce network noise by 70%.
6. Outcome & Learnings
Key Learnings
- →Binary protocols like Yjs are essential for scaling real-time apps beyond simple text.
- →Static Regeneration (ISR) is more reliable for docs than pure dynamic databases.
- →Automating the Git flow via API bridges the gap between 'editor' and 'repository'.
- →Effective presence indicators are a UX requirement for collaborative tools.
What I'd Improve Next
- ○Implement offline-first capabilities using IndexedDB persistence.
- ○Add support for collaborative visual diagramming using Tldraw.