Repository navigation
Building tracked-changes + DOCX round-trip on Lexical with Yjs #7953
Replies: 1 comment
|
This is a great fit for Lexical, but what you’re trying to build is essentially three hard problems stacked together:
Lexical can handle all of this, but only if you design the data model + history model carefully from the start. 🧠 1. Track changes (“suggesting mode”) in Lexical + YjsLexical does NOT provide built-in “track changes”, so you implement it as a parallel operation layer, not as normal editor state. ✅ Recommended pattern: “dual-layer editing model”Instead of directly applying edits: Layer 1 — actual document (Yjs)Y.Doc → authoritative shared stateLayer 2 — suggestion layer (your custom plugin)Insert/Delete/Format operations stored as metadata nodes🔥 Core ideaEvery edit becomes: {
type: "insert" | "delete" | "format",
userId,
timestamp,
status: "pending" | "accepted" | "rejected",
payload: LexicalNodeChange
}Instead of immediately mutating final text. 🧩 Implementation patternWrap all writes:editor.update(() => {
// instead of directly applying
// you create a "suggestion node"
});Example: suggestion nodeclass SuggestionNode extends DecoratorNode {
__status;
__author;
__originalNode;
}✔ Accept / Reject flow
⚡ 2. Yjs scaling (10k–50k words docs)This is where most systems break if not tuned. 🚨 Key rule
✅ Best practice structureInstead of one big text node: Use block-based segmentationDocument
├── Paragraph 1 (Y.Text)
├── Paragraph 2 (Y.Text)
├── Paragraph 3This avoids:
🧠 Awareness strategies1. batching updatesdoc.transact(() => {
// multiple edits grouped
});2. debounce remote updatesEspecially for typing: updateTimeout = setTimeout(sync, 50–100ms);3. avoid deep object nestingYjs performs best with: ✔ flat maps 🧹 Garbage collection tipEnable: gc: trueBut be careful:
👉 For track-changes, you often disable GC for “audit layer” data 📄 3. DOCX ↔ Lexical round-trip (hardest part)This is NOT a Lexical problem — it is a schema mapping problem.
|
| DOCX | HTML | Lexical |
|---|---|---|
| paragraph | <p> |
ParagraphNode |
| bold | <strong> |
TextStyle.bold |
| heading | <h1> |
HeadingNode |
| comment | data-attr | SuggestionNode |
⚠️ Round-trip limitation
You must accept:
❌ perfect fidelity is impossible
✔ semantic fidelity is achievable
🧾 4. Versioning + audit trail (human vs machine)
This is where Lexical + Yjs actually shines.
✅ Recommended approach: operation log layer
Store operations separately:
OperationLogEntry = {
id,
userId,
source: "human" | "ai",
timestamp,
change: YjsUpdate | LexicalMutation
}🧠 Best design
Do NOT embed this inside nodes.
Instead:
✔ external log (database)
✔ linked via node IDs
🔍 Enables:
- audit reports
- diff timeline
- rollback
- compliance tracking
🚀 5. Suggested architecture (clean version)
┌──────────────┐
│ React UI │
└──────┬───────┘
│
┌──────▼───────┐
│ Lexical │ ← UI state layer
└──────┬───────┘
│
┌──────────────▼──────────────┐
│ Suggestion / Track Layer │
│ (custom plugin system) │
└──────────────┬───────────────┘
│
┌──────▼───────┐
│ Yjs │ ← real-time sync
└──────┬───────┘
│
┌──────▼───────┐
│ persistence │
└──────────────┘
⚠️ Key caveats (important)
1. Lexical is not Google Docs
You must build:
- suggestion UI
- diff engine
- revision model
yourself.
2. Yjs is not version control
It gives:
- sync
- CRDT merging
NOT:
- history tree
- approval workflow
3. DOCX export is always lossy
Unless you restrict features heavily.
🧠 Final recommendation
If your goal is academic copy-editing platform:
✔ Lexical + Yjs is a good base
✔ but track-changes must be custom layer
✔ DOCX must be treated as import/export format only, not source of truth
🚀 Summary
To build what you want:
- ✔ Use Yjs for real-time sync
- ✔ Build custom suggestion layer (don’t rely on Lexical core)
- ✔ Use paragraph-based Yjs structure for scaling
- ✔ Use HTML intermediate for DOCX conversion
- ✔ Maintain external audit log for versioning
If this answer helped or pointed you in the right direction, I'd appreciate it if you could mark it as the accepted answer so it's easier for others with the same issue to find.
Also, if you found my contribution useful, I'd appreciate it if you could check out my GitHub profile, follow me, and star any repositories you find interesting.
GitHub: https://github.com/Advait251206
Uh oh!
There was an error while loading. Please reload this page.
Hi Lexical team! My team is trying to build an academic copy-editing platform and evaluating Lexical. We need:
Environment: React 18, Lexical (latest), Yjs (custom provider), Pandoc/Mammoth for conversion (TBD).
So questions: recommended patterns/examples for suggestion mode & diff/merge? limits/caveats for very large docs with Yjs? schema tips that help clean DOCX export later?
All reactions