# yjs-demo

**Repository Path**: feng-xiaohan/yjs-demo

## Basic Information

- **Project Name**: yjs-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Yjs 协作编辑 Demo

体验 [Yjs](https://docs.yjs.dev/) CRDT 实时协同：协作文本（`Y.Text` + CodeMirror）与类 JSON 字段（`Y.Map`）。

与 Cosine 现有「悲观锁 + 手动保存」对比，用于评估协同编辑是否适合你们的 JSON 页面场景。参见 `doc-edit/seamless-auto-save.md`。

## 快速开始

```bash
cd YJS
pnpm install
pnpm dev
```

浏览器打开 http://localhost:5175（**默认 Broadcast 模式**）

### 三种同步模式

| 模式 | 说明 |
|------|------|
| **Broadcast**（默认） | 同源多 Tab；使用与 `y-websocket` 相同的 SyncStep1/2 协议 + `lib0/broadcastchannel` |
| **Local** | 单页左右两个编辑器共享同一 `Y.Doc` |
| **WebSocket** | 多浏览器/多机器；需先启动 relay |

#### 多 Tab 体验（Broadcast）

1. 打开 http://localhost:5175 ，确认模式为 **Broadcast**，Room 为 `cosine-yjs-demo`
2. **复制同一地址** 到新 Tab（勿混用 `localhost` 与 `127.0.0.1`）
3. Tab1 编辑 → Tab2 应实时更新；**后开的 Tab 会拉取已有全文**
4. 右上角显示 **「已同步」** 后再编辑

#### WebSocket 模式

```bash
# 终端 1
pnpm ws

# 终端 2
pnpm dev
```

两个浏览器窗口访问同一 Room 即可协同。

## 实现说明

`BroadcastProvider` 对齐 `y-websocket` 的 BroadcastChannel 层：

- 加入时发送 **SyncStep1 + SyncStep2**，新 Tab 获取完整文档
- 增量 update / Awareness 与 WebSocket 模式一致
- 示例内容在 **同步完成后** 才 seed（避免多 Tab 重复插入默认文案）

## 目录结构

```
YJS/
├── src/
│   ├── DemoApp.tsx
│   ├── hooks/useCollabSession.ts
│   ├── providers/broadcastProvider.ts
│   ├── utils/demoContent.ts
│   └── components/
│       ├── CollabEditor.tsx
│       └── JsonMapPane.tsx
└── package.json
```

## 依赖

- [yjs](https://github.com/yjs/yjs) — CRDT 核心
- [y-protocols](https://github.com/yjs/y-protocols) — sync / awareness 协议
- [lib0](https://github.com/dmonad/lib0) — BroadcastChannel 封装
- [y-codemirror.next](https://github.com/yjs/y-codemirror.next) — 编辑器绑定
- [y-websocket](https://github.com/yjs/y-websocket) — WebSocket Provider