Skip to main content

Documentation Index

Fetch the complete documentation index at: https://s2.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Y-S2 is a Cloudflare Worker that provides real-time collaborative document editing using Yjs with S2 as the distribution channel and an R2 bucket as the storage provider. It provides scalable WebSocket-based document synchronization where document updates are made durable on an S2 stream and distributed to connected clients and reactively persisted to the R2 bucket.

​
Getting Started

​
Prerequisites

  • Cloudflare account with Workers enabled
  • S2.dev account with a basin that has Create stream on append/read enabled
  • Scoped access token to your S2 basin
  • R2 bucket for snapshot storage

​
Environment Variables

S2_ACCESS_TOKEN=your_s2_access_token
S2_BASIN=your_s2_basin_name
R2_BUCKET=your_r2_bucket_name
LOG_MODE=CONSOLE|S2_SINGLE|S2_SHARED  # Optional
SNAPSHOT_BACKLOG_SIZE=100             # Optional

​
Deployment

# Install dependencies
npm install

# Deploy to Cloudflare Workers
npm run deploy

# Or run locally for development
npm run dev

​
Client Integration

Connect to the deployed worker using the Yjs WebSocket provider: 
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const provider = new WebsocketProvider(
  'wss://your-worker.your-subdomain.workers.dev',
  'room-name',
  doc,
  {
    params: { authToken: 'your-auth-token' }
  }
)

​
How It Works

  1. Document Updates: When users make changes to a Yjs document, updates are sent to the Y-S2 worker via WebSocket
  2. S2: Updates are appended to an S2 stream for durability and real-time distribution
  3. Client Distribution: Connected clients receive updates in real-time through WebSocket connections
  4. R2 Persistence: Document snapshots are periodically saved to R2 bucket storage for efficient loading

​
Resources