Yorkie

Revisions

Revisions provide version control for Yorkie documents, allowing you to save snapshots at specific points in time, browse history, and restore previous states. This guide explains how to integrate revision features into your application.

Overview

Revisions are immutable snapshots of a document's state stored on the server. Each revision contains:

• Label: A user-friendly identifier (e.g., "v1.0", "Draft", "Final")
• Description: Optional detailed explanation of what changed
• Snapshot: The complete document state in YSON format
• Timestamp: When the revision was created
• Server Sequence: The document's server sequence number at creation time

Use Cases

• Version History: Allow users to browse and restore previous document versions
• Milestone Tracking: Save important states before major changes
• Audit Trail: Maintain a record of document evolution over time
• Collaboration Review: Preview changes before accepting them
• Rollback: Recover from unwanted changes or errors

Before You Begin

This guide assumes familiarity with:

1. Client and Document basics
2. YSON format for understanding snapshots

How Revisions Work

When you create a revision:

1. The server builds the current document state
2. The state is serialized to YSON format (data only, no CRDT metadata)
3. The revision is stored with metadata in the database
4. A RevisionSummary is returned to the client

API Reference

For detailed API documentation, see JS SDK - Document Revisions.

Building a Revision UI

This section shows how to build a revision management interface, using patterns from CodePair as a reference.

React Hook (Recommended)

@yorkie-js/react provides a built-in useRevisions hook that wraps the client's revision API and automatically binds the current client and document. Use it inside a DocumentProvider:

import { useState, useEffect } from 'react';
import { useRevisions } from '@yorkie-js/react';
import type { RevisionSummary } from '@yorkie-js/react';

function RevisionPanel() {
  const { createRevision, listRevisions, getRevision, restoreRevision } =
    useRevisions();
  const [revisions, setRevisions] = useState<RevisionSummary[]>([]);

  useEffect(() => {
    listRevisions({ pageSize: 20, isForward: false }).then(setRevisions);
  }, [listRevisions]);

  const handleCreate = async () => {
    const label = `v${new Date().toISOString().split('T')[0]}`;
    await createRevision(label, 'Manual checkpoint');
    setRevisions(await listRevisions({ pageSize: 20 }));
  };

  const handlePreview = async (revisionId: string) => {
    const revision = await getRevision(revisionId);
    // Display revision.snapshot in a preview dialog
  };

  const handleRestore = async (revisionId: string) => {
    if (confirm('Restore to this revision? Current state will be replaced.')) {
      await restoreRevision(revisionId);
      setRevisions(await listRevisions({ pageSize: 20 }));
    }
  };

  return (
    <div>
      <button onClick={handleCreate}>Save Revision</button>
      <ul>
        {revisions.map((rev) => (
          <li key={rev.id}>
            <span>{rev.label}</span>
            <span>{new Date(rev.createdAt).toLocaleString()}</span>
            <button onClick={() => handlePreview(rev.id)}>Preview</button>
            <button onClick={() => handleRestore(rev.id)}>Restore</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

The hook returns four methods:

For the full hook API reference, see React SDK - useRevisions.

For a complete working example, see the react-revision example.

Manual Approach

If you need custom loading/error state management or aren't using DocumentProvider, you can build a custom hook using the client API directly:

1import { useState, useCallback, useEffect } from 'react';
2import { Client, Document, RevisionSummary } from '@yorkie-js/sdk';
3
4export function useCustomRevisions(client: Client | null, doc: Document<any, any> | null) {
5  const [revisions, setRevisions] = useState<RevisionSummary[]>([]);
6  const [isLoading, setIsLoading] = useState(false);
7
8  const fetchRevisions = useCallback(async () => {
9    if (!client || !doc) return;
10    setIsLoading(true);
11    try {
12      const revs = await client.listRevisions(doc, { pageSize: 50, isForward: false });
13      setRevisions(revs);
14    } finally {
15      setIsLoading(false);
16    }
17  }, [client, doc]);
18
19  const createRevision = useCallback(async (label: string, description?: string) => {
20    if (!client || !doc) throw new Error('Client or document not available');
21    setIsLoading(true);
22    try {
23      const revision = await client.createRevision(doc, label, description);
24      await fetchRevisions();
25      return revision;
26    } finally {
27      setIsLoading(false);
28    }
29  }, [client, doc, fetchRevisions]);
30
31  useEffect(() => {
32    if (client && doc) fetchRevisions();
33  }, [client, doc, fetchRevisions]);
34
35  return { revisions, isLoading, createRevision, fetchRevisions };
36}

Previewing Snapshots

Use the YSON parser to convert snapshots into readable data:

1import { YSON } from '@yorkie-js/sdk';
2
3async function previewRevision(revisionId: string) {
4  const revision = await client.getRevision(doc, revisionId);
5
6  if (revision.snapshot) {
7    // Parse YSON to get document data
8    const data = YSON.parse<YourDocType>(revision.snapshot);
9
10    // For Text fields, convert to plain string
11    if (data.content) {
12      const plainText = YSON.textToString(data.content);
13      console.log('Document content:', plainText);
14    }
15  }
16}

Restoration Flow

When restoring a revision, the server:

1. Loads the revision's YSON snapshot
2. Creates a new document state from the snapshot
3. Applies the change through the CRDT merge process
4. Syncs the restored state to all connected clients

Auto-Revisions

Yorkie can automatically create revisions during snapshot creation. This is controlled by the auto-revision-enabled project setting.

When enabled:

• Revisions are created automatically during garbage collection snapshots
• Labels follow the format: snapshot-{serverSeq}
• Descriptions: Auto created revision of snapshot #{serverSeq}

Configure via the Dashboard or Admin API. See Resources for details.

Best Practices

When to Create Revisions

• Before major edits: Save state before significant changes
• At milestones: Mark completion of features or sections
• Periodically: For long editing sessions, create time-based checkpoints
• Before restore: Always save current state before restoring an old revision

Labeling Conventions

Use consistent, descriptive labels:

Storage Considerations

• Revisions store full document snapshots, not deltas
• Each revision consumes storage proportional to document size
• Use auto-revisions judiciously for large documents
• Consider periodic cleanup of old revisions if storage is a concern

Permissions

Revision operations require appropriate document permissions:

Related Documentation

• JS SDK - Document Revisions - Complete API reference
• React SDK - useRevisions - React hook for revision management
• YSON - Understanding snapshot format
• Resources - Project configuration including auto-revisions
• CodePair - Reference implementation