Skip to content

README.md

Latest commit

 

History

History
308 lines (215 loc) · 11.2 KB

README.md

File metadata and controls

308 lines (215 loc) · 11.2 KB

SyncKit Documentation

Welcome to SyncKit! Build collaborative, offline-first apps without the complexity.

✨ What's New in v0.2.0

Everything you need for real-time collaboration.

v0.2.0 is production-ready with features that used to take months to build:

  • ✍️ Rich text editing - Formatting conflicts resolved automatically (Peritext CRDT)
  • ↩️ Cross-tab undo/redo - Works across browser tabs and persists across sessions
  • 👥 Live presence - See who's editing in real-time
  • 🖱️ Cursor sharing - Watch teammates type with animated cursors
  • 🎯 Counters & Sets - PN-Counter and OR-Set CRDTs for distributed state
  • ⚛️ Framework adapters - React, Vue 3, and Svelte 5 ready to use

Backed by 1,081 passing tests (87% coverage). Zero critical bugs. Production-ready.

Get started in 5 minutes →

🚀 Getting Started

New to SyncKit? Start here:

📖 User Guides

Learn core concepts and patterns:

Core Concepts

Advanced Topics

🔄 Migration Guides

Switching from another platform or upgrading?

📚 API Reference

Complete API documentation:

Core SDK

Framework Adapters

  • React Hooks - useSyncText, useRichText, useCounter, useSet, usePresence, useCursor, useUndoRedo
  • Vue 3 Integration - Complete guide with composables and Composition API patterns
  • Svelte 5 Integration - Reactive stores with runes support and context patterns

Server API

🏗️ Architecture

Understand how SyncKit works:

💡 Examples

Learn from working examples:

Basic Examples

  • Todo App - Simple CRUD with offline support
    • Demonstrates: Document API, offline persistence, real-time sync

Advanced Examples

  • Collaborative Editor - Real-time text editing with CodeMirror 6

    • Demonstrates: Text CRDT, multi-document support, offline-first editing, live presence

  • Project Management App - Production-grade kanban board

    • Demonstrates: Drag-and-drop with @dnd-kit, task management, team collaboration, shadcn/ui components

🎓 Concepts

Local-First Principles

What is Local-First?

  • Local database is the source of truth
  • Network is optional (optimization, not requirement)
  • Instant UI updates (<1ms)
  • Works perfectly offline

Key Benefits:

  • ✅ Speed: No network round-trips for reads
  • ✅ Reliability: Works without internet
  • ✅ Privacy: Data stays local by default
  • ✅ Ownership: You control your data

Learn more about offline-first →

Conflict Resolution

How Conflicts Work:

  • Two clients edit same field while disconnected
  • Both sync when back online
  • SyncKit merges automatically

Strategies:

  • LWW (Last-Write-Wins) - Default, works for 95% of cases
  • Custom Handlers - Custom logic for specific fields
  • Text CRDTs - Character-level merge for collaborative editing

Learn more about conflicts →

Performance

Bundle Size (gzipped):

  • Default variant: 154KB (everything included - text editing, rich text, undo/redo, presence, cursors, framework adapters)
  • Lite variant: 46KB (basic sync only)
  • What you get: For 154KB, you're shipping production-ready collaboration without building it yourself

Speed:

  • Local updates: <1ms (instant user feedback)
  • Network sync: 10-50ms p95 (faster than most REST APIs)
  • Multi-client convergence: <100ms (real-time collaboration)

Stress-tested: 24-hour continuous operation, 1,081 tests, zero memory leaks.

Learn more about performance → | Bundle size optimization →

🧪 Testing

Learn how to test offline-first apps:

Full testing guide →

🔧 Troubleshooting

Common Issues

Module not found: @synckit-js/sdk

# Core SDK (includes React hooks via @synckit-js/sdk/react)
npm install @synckit-js/sdk

# React is a peer dependency if you use the React hooks
npm install react

QuotaExceededError: IndexedDB quota exceeded

// Request persistent storage
if (navigator.storage && navigator.storage.persist) {
  await navigator.storage.persist()
}

Changes not syncing across tabs

// ✅ Cross-tab sync via BroadcastChannel is fully implemented
// Changes sync automatically across tabs via BroadcastChannel API
// Multi-tab scenarios work both locally (BroadcastChannel) and via server
const todo = sync.document<Todo>('todo-1')  // Same ID in both tabs - syncs automatically!

TypeScript errors

// Define your interface
interface Todo {
  id: string
  text: string
  completed: boolean
  dueDate?: Date  // Optional fields with ?
}

// Use with document
const todo = sync.document<Todo>('todo-1')

More troubleshooting →

🤝 Community & Support

Get Help

Contributing

We welcome contributions!

📊 Status

Current Release: v0.2.0 (December 2025) Production Ready: Complete local-first collaboration platform ✅

What's Complete ✅

  • ✅ Text CRDT (Fugue) - Collaborative text editing with conflict-free convergence
  • ✅ Rich Text (Peritext) - Bold, italic, links with formatting conflict resolution
  • ✅ Undo/Redo - Cross-tab undo with persistent history
  • ✅ Awareness & Presence - Real-time user tracking
  • ✅ Cursor Sharing - Live cursor positions with animations
  • ✅ Counters & Sets - PN-Counter and OR-Set CRDTs
  • ✅ Vue 3 Adapter - Complete composables with Composition API
  • ✅ Svelte 5 Adapter - Reactive stores with runes support
  • ✅ Core Rust engine (LWW sync, full CRDT suite, protocol)
  • ✅ TypeScript SDK (Document, Text, RichText, Counter, Set APIs)
  • ✅ Network sync layer (WebSocket, offline queue, auto-reconnect)
  • ✅ Cross-tab sync (BroadcastChannel + server-mediated)
  • ✅ React integration (complete hook library for all features)
  • ✅ TypeScript server (WebSocket sync, JWT auth, PostgreSQL)
  • ✅ Example applications (todo app, collaborative editor, project management)
  • ✅ 1,081+ tests (87% coverage)
  • ✅ Documentation (complete API reference, guides, migration docs)
  • ✅ Formal verification (TLA+, 118K states explored)

What's Next 🚧

  • 🚧 Multi-language servers (Python, Go, Rust)
  • 🚧 Advanced storage adapters (OPFS, SQLite)
  • 🚧 Performance optimization (large documents >10K chars)

Full roadmap →

📝 License

MIT License - see LICENSE for details.

🔗 Quick Links

Happy syncing! 🚀

Questions? Check the guides, API docs, or open an issue.