Storage

Storage depends on how your users edit.

For real-time collaboration, store the Yjs document state. That is the live source of truth. A DOCX file can seed an empty room, and you can export DOCX snapshots whenever you need Word interop, downloads, audit records, or pinned versions.

For single-user or check-in/check-out flows, store DOCX versions directly.

Storage approaches

Collaboration level	Approach	Canonical store	When changes are stored
High	Yjs/CRDT	Yjs update or snapshot	Continuously on the backend
Low	Check in/out	DOCX binary	When the user saves or checks in

High collaboration

For real-time, multi-user collaboration, each client connects to a real-time collaboration service. Only Yjs updates move through that service. The collaboration server merges those updates and stores the current Yjs state.

Complexity: medium: Requires a server-side Yjs service

How it works:

• The first DOCX can seed an empty room.
• After that, the Yjs document is canonical.
• Each edit is sent as a Yjs update over WebSocket.
• The server stores Yjs updates or periodic Yjs snapshots.
• SuperDoc exports a fresh DOCX from the current Yjs-backed editor state when you need a file.

import * as Y from "yjs";

async function loadYdoc(documentId: string) {
  const ydoc = new Y.Doc();
  const update = await storage.get(`ydocs/${documentId}.bin`);

  if (update) {
    Y.applyUpdate(ydoc, new Uint8Array(update));
  }

  return ydoc;
}

async function saveYdoc(documentId: string, ydoc: Y.Doc) {
  const update = Y.encodeStateAsUpdate(ydoc);
  await storage.put(`ydocs/${documentId}.bin`, Buffer.from(update));
}

The Yjs document carries the document body, package parts, media, comments, and document metadata needed for SuperDoc to rebuild the editor state.

DOCX archive snapshots

DOCX exports are still useful in real-time collaboration. They are just not the live collaboration store.

Use DOCX exports for:

• User downloads
• Word or Microsoft 365 workflows
• Audit snapshots
• Version pinning
• Legal review packages
• Backup and restore workflows

const blob = await superdoc.export({
  triggerDownload: false,
  isFinalDoc: true,
});

await storage.put(`versions/${documentId}/${versionId}.docx`, blob);

Low collaboration

For scenarios where one user edits at a time, use a locking flow. Users check out a document, edit it, and save or check it back in.

Complexity: low: Requires storing and querying document lock state

How it works:

• The active user opens a DOCX.
• Your app prevents other users from editing the same document.
• On save or check-in, export a DOCX and upload it to your backend.

1. Create a version ID

   Generate a unique identifier for the document version.

   document_revision1764976265.docx
   
2. Export the DOCX

   Ask SuperDoc for the raw Blob so your app can upload it.

   const blob = await superdoc.export({
     triggerDownload: false,
     isFinalDoc: true,
   });
   
3. Store the version

   Save the DOCX binary to your storage layer.

   s3://documents_bucket/versions/document_revision1764976265.docx
   
4. Save metadata

   Store the version ID, storage path, author, and timestamp in your database.

Export methods

The export APIs are covered in Import/Export.

Best practices

Store Yjs for live rooms

In real-time collaboration, store Yjs updates or snapshots as the canonical state.

Export DOCX snapshots

Create DOCX versions for downloads, audit records, Word workflows, and pinned releases.

Keep version history

Store enough history to audit, compare, and recover documents.

Use durable storage

Use S3, Google Cloud Storage, Azure Blob Storage, PostgreSQL, or your existing storage layer.