> ## 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

> Build durable Yjs collaborative editing with y-s2, using S2 streams for updates and Cloudflare R2 for snapshots.

Y-S2 is a Cloudflare Worker that provides real-time collaborative document editing using [Yjs](https://yjs.dev) 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

```bash theme={null}
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

```bash theme={null}
# 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:

```javascript theme={null}
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

* [Demo](https://s2.dev/demos/y-s2)
* [GitHub Repository](https://github.com/s2-streamstore/y-s2)
* [Yjs Documentation](https://docs.yjs.dev)