메뉴
Yjs WebSocket server implementation guide for real-time collaboration. Configure y-websocket, awareness cursors, and persistence with production-ready patterns.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/platxa/platxa-skill-generator --skill platxa-yjs-server명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | platxa-yjs-server |
| description | Yjs WebSocket server implementation guide for real-time collaboration. Configure y-websocket, awareness cursors, and persistence with production-ready patterns. |
| allowed-tools | ["Read","Glob","Grep"] |
| suggests | ["platxa-sidecar-builder"] |
| metadata | {"version":"1.0.0","tags":["guide","yjs","websocket","collaboration","crdt"]} |
| user-invocable | true |
Guide for implementing Yjs WebSocket servers for real-time collaborative editing in the Platxa platform.
This skill covers the server-side implementation of Yjs CRDT synchronization:
| Component | What You Can Configure |
|---|---|
| y-websocket Server | WebSocket setup, room management, connection handling |
| Awareness Protocol | User presence, cursor positions, selection highlighting |
| Persistence | LevelDB, IndexedDB, file system, git integration |
| Authentication | JWT validation, session management, single-user enforcement |
| Error Handling | Reconnection, conflict resolution, graceful degradation |
When implementing a Yjs server, follow this workflow:
Determine your requirements:
Choose implementation approach:
setupWSConnection for quick startAdd user presence features:
Select storage backend based on needs:
import { WebSocketServer } from 'ws';
import { setupWSConnection } from 'y-websocket/bin/utils';
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', (ws, req) => {
setupWSConnection(ws, req);
});
console.log('Yjs server running on ws://localhost:1234');
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
const doc = new Y.Doc();
const provider = new WebsocketProvider(
'ws://localhost:1234',
'my-room',
doc
);
// Access shared types
const yText = doc.getText('content');
// Listen for sync
provider.on('sync', (synced: boolean) => {
console.log('Synced:', synced);
});
Minimal setup for local development:
import { WebSocketServer } from 'ws';
import { setupWSConnection } from 'y-websocket/bin/utils';
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', setupWSConnection);
JWT validation before allowing connection:
import { WebSocketServer } from 'ws';
import { setupWSConnection } from 'y-websocket/bin/utils';
import jwt from 'jsonwebtoken';
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', (ws, req) => {
// Get token from Sec-WebSocket-Protocol header
const token = req.headers['sec-websocket-protocol'];
try {
const payload = jwt.verify(token, process.env.JWT_SECRET);
// Store user info for awareness
(ws as any).user = payload;
setupWSConnection(ws, req);
} catch (err) {
ws.close(4001, 'Unauthorized');
}
});
Documents survive server restarts:
import { WebSocketServer } from 'ws';
import { setupWSConnection, setPersistence } from 'y-websocket/bin/utils';
import { LeveldbPersistence } from 'y-leveldb';
const ldb = new LeveldbPersistence('./yjs-data');
setPersistence({
bindState: async (docName, ydoc) => {
const persistedYdoc = await ldb.getYDoc(docName);
const state = Y.encodeStateAsUpdate(persistedYdoc);
Y.applyUpdate(ydoc, state);
ydoc.on('update', (update) => {
ldb.storeUpdate(docName, update);
});
},
writeState: async (docName, ydoc) => {
// Called on document close
}
});
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', setupWSConnection);
Full setup with authentication, single-user, and file persistence:
import { WebSocketServer } from 'ws';
import * as Y from 'yjs';
import { encoding, decoding, syncProtocol, awarenessProtocol } from 'y-protocols';
import fs from 'fs/promises';
const docs = new Map<string, Y.Doc>();
const sessions = new Map<string, { userId: string; expiry: number }>();
async function handleConnection(ws, req, user) {
const docPath = req.url.replace('/ws/doc/', '');
// Single-user check (bypass for AI)
if (user.client_type !== 'ai') {
const existing = sessions.get(docPath);
if (existing && existing.userId !== user.id && existing.expiry > Date.now()) {
ws.close(4003, 'Document locked by another user');
return;
}
sessions.set(docPath, { userId: user.id, expiry: Date.now() + 30000 });
}
// Get or create Y.Doc
let doc = docs.get(docPath);
if (!doc) {
doc = new Y.Doc();
// Initialize from file system
try {
const content = await fs.readFile(`/mnt/addons/${docPath}`, 'utf-8');
doc.getText('content').insert(0, content);
} catch (e) {
// New file
}
docs.set(docPath, doc);
}
// Setup sync protocol
// ... (see references/websocket-api.md for full protocol)
}
// Client-side
provider.awareness.setLocalState({
id: user.id,
name: user.name,
color: generateColor(user.id),
colorLight: generateColor(user.id, 0.9),
cursor: null // Updated by Monaco binding
});
function generateColor(id: string, lightness = 0.45) {
const hue = hashString(id) % 360;
return `hsl(${hue}, 70%, ${lightness * 100}%)`;
}
function getConnectedUsers(provider: WebsocketProvider) {
const users: UserPresence[] = [];
provider.awareness.getStates().forEach((state, clientId) => {
if (state && clientId !== provider.awareness.clientID) {
users.push(state as UserPresence);
}
});
return users;
}
// Listen for changes
provider.awareness.on('change', () => {
const users = getConnectedUsers(provider);
updateUserList(users);
});
import { MonacoBinding } from 'y-monaco';
const binding = new MonacoBinding(
yText,
editor.getModel(),
new Set([editor]),
provider.awareness // Pass awareness for cursor sync
);
User: "Set up a simple Yjs server for collaborative text editing"
Response:
Server (server.ts):
import { WebSocketServer } from 'ws';
import { setupWSConnection } from 'y-websocket/bin/utils';
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', (ws, req) => {
console.log('Client connected');
setupWSConnection(ws, req);
});
Client (client.ts):
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
const doc = new Y.Doc();
const provider = new WebsocketProvider('ws://localhost:1234', 'document', doc);
// Setup awareness
provider.awareness.setLocalState({
name: 'User ' + Math.floor(Math.random() * 100),
color: `hsl(${Math.random() * 360}, 70%, 45%)`
});
const yText = doc.getText('content');
yText.observe(() => {
console.log('Content:', yText.toString());
});
User: "Handle multiple documents with JWT auth"
Response:
import { WebSocketServer } from 'ws';
import * as Y from 'yjs';
import jwt from 'jsonwebtoken';
const docs = new Map<string, Y.Doc>();
function getDoc(roomName: string): Y.Doc {
if (!docs.has(roomName)) {
docs.set(roomName, new Y.Doc());
}
return docs.get(roomName)!;
}
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', (ws, req) => {
const token = req.headers['sec-websocket-protocol'];
try {
const user = jwt.verify(token, process.env.JWT_SECRET) as any;
const roomName = new URL(req.url, 'http://localhost').searchParams.get('room');
if (!roomName) {
ws.close(4000, 'Room name required');
return;
}
const doc = getDoc(roomName);
// Setup Yjs sync for this doc...
} catch (err) {
ws.close(4001, 'Invalid token');
}
});
User: "Documents should persist and have version history"
Response:
import { WebSocketServer } from 'ws';
import { LeveldbPersistence } from 'y-leveldb';
import { setPersistence, setupWSConnection } from 'y-websocket/bin/utils';
import simpleGit from 'simple-git';
import fs from 'fs/promises';
const ldb = new LeveldbPersistence('./yjs-data');
const git = simpleGit('./workspace');
// Setup persistence
setPersistence({
bindState: async (docName, ydoc) => {
// Load from LevelDB
const persisted = await ldb.getYDoc(docName);
Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(persisted));
// Track updates
ydoc.on('update', async (update) => {
await ldb.storeUpdate(docName, update);
});
},
writeState: async (docName, ydoc) => {
// On document close, write to file and commit
const content = ydoc.getText('content').toString();
const filePath = `./workspace/${docName}`;
await fs.writeFile(filePath, content);
await git.add(filePath);
await git.commit(`Update ${docName}`, { '--author': 'Yjs Server <yjs@local>' });
}
});
const wss = new WebSocketServer({ port: 1234 });
wss.on('connection', setupWSConnection);
| Practice | Implementation |
|---|---|
| Auth via header | Use Sec-WebSocket-Protocol, not query params |
| Validate JWT | Check signature, expiry, and claims |
| Rate limiting | Limit connections per IP/user |
| Path validation | Prevent directory traversal in doc names |
| Practice | Implementation |
|---|---|
| One Y.Doc per file | Don't share docs across unrelated content |
| Debounce persistence | Write to disk every 300ms, not every update |
| Cleanup on disconnect | Destroy Y.Doc when last client leaves |
| Monitor memory | Track doc count and memory usage |
| Practice | Implementation |
|---|---|
| Exponential backoff | Client reconnection: 1s, 2s, 4s, 8s... max 30s |
| Client persistence | Use y-indexeddb for offline support |
| Server persistence | Use y-leveldb for crash recovery |
| Audit trail | Git commits for version history |
Symptom: WebSocket connection fails immediately
Causes & Fixes:
Sec-WebSocket-Protocol header, not BearerSymptom: Can't see other users' cursors
Causes & Fixes:
new MonacoBinding(yText, model, editors, awareness)provider.wsconnectedprovider.awareness.getLocalState()Symptom: All content lost on server restart
Causes & Fixes:
bindState loads persisted contentSymptom: Node.js process memory increasing
Causes & Fixes:
After implementing Yjs server, verify:
platxa-monaco-config skill for editor setupYjsProvider, useYjsDocument, useMonacoBindingreferences/awareness-protocol.mdreferences/persistence-options.mdreferences/websocket-api.mdAutonomous skill creator for Claude Code CLI. Use when the user asks to "create a skill", "generate a skill", or "build a new slash command". Uses multi-phase orchestrated workflow with Task tool subagents to research domains, design architecture, generate content, validate quality, and iteratively improve via eval infrastructure. Creates production-ready skills following the Agent Skills open standard and Claude Code extensions.
Automatically generates and improves code documentation across Python, JavaScript/TypeScript, Java, Go, and Rust. Detects language conventions, applies appropriate docstring standards, and validates documentation quality.
Generate conventional commit messages by analyzing staged git changes. Detects change type, suggests scope, and formats messages following the Conventional Commits specification.