CRDT Design Guide

A comprehensive guide to designing collaborative data structures using Yjs and CRDTs for real-time applications.

Overview

Building collaborative applications requires careful consideration of how data structures behave when multiple users edit simultaneously. This guide covers the design patterns, best practices, and common pitfalls when working with Conflict-free Replicated Data Types (CRDTs) in Cloudillo applications.

Early Stage Documentation

The patterns in this guide are based on internal Cloudillo applications (Calcillo, Ideallo, Prezillo, Quillo) which have shown promising results in our testing. However, Cloudillo has not yet achieved wide adoption, so these recommendations should be considered with appropriate caution. We’re sharing our experience to help the community, but real-world usage at scale may reveal patterns that need adjustment.

Who This Guide Is For

This guide is for developers who:

  • Are building collaborative features in Cloudillo applications
  • Need to understand how to structure data for real-time synchronization
  • Want to learn from real-world patterns used in Cloudillo apps (Calcillo, Ideallo, Prezillo, Quillo)

Prerequisites

Before diving in, you should be familiar with:

  • Basic JavaScript/TypeScript
  • The CRDT API for Cloudillo integration
  • General concepts of collaborative editing

Topics

Fundamentals

Core Yjs concepts including shared types, document structure, and how CRDTs work internally.

Design Patterns

Proven patterns for structuring collaborative data: ID-based storage, nested maps, content separation, and more.

Application Types

Specific guidance for different document types: text editors, spreadsheets, canvas/whiteboard apps, and presentations.

Collaboration Features

Implementing multi-user features: transactions, undo/redo, presence awareness, and conflict resolution.

Pitfalls

Common mistakes that cause data corruption, sync issues, or unexpected behavior—and how to avoid them.

Quick Start

If you’re new to CRDT design, start with:

  1. Shared Types - Understand Y.Map, Y.Array, Y.Text
  2. ID-Based Storage - The most important pattern for collaborative apps
  3. Transactions - Properly batching changes

See Also