@yjsync/core

Runtime-agnostic Yjs room session: y-websocket-compatible binary protocol (MESSAGE_SYNC, MESSAGE_AWARENESS), optional persistence, compaction, and JSON export helpers.

Use this when you are building your own transport (custom Worker glue, tests) and want shared room logic without importing Cloudflare SDKs.

Install

bun add @yjsync/core yjs

Minimal in-memory room

import { MemoryPersistenceAdapter, RoomSession } from '@yjsync/core'

const room = new RoomSession('my-room-id', {
  persistence: new MemoryPersistenceAdapter(),
  compactAfterTailSize: 256,
})

await room.whenReady

await room.addConnection(myConnHandle, {
  send: (data) => ws.send(data),
  readyState: ws.readyState,
  close: () => ws.close(),
})

room.handleMessage(myConnHandle, incomingUint8Array)

RoomSession extends Y.Doc. Use room.awareness for collaboration cursors when your client supports it.

JSON export

import { exportJsonToApi } from '@yjsync/core'
import { serializeTiptap } from '@yjsync/serializers'

await exportJsonToApi({
  roomId: 'demo/doc-1',
  doc: roomSession,
  url: 'https://api.example.com/snapshots',
  revision: roomSession.revision,
  serialize: serializeTiptap,
})

JSON serializers (TipTap, root map, ProseMirror fragment, custom maps) live in @yjsync/serializers. The default in exportJsonToApi (when no serialize is passed) is doc.getMap('root').toJSON().

Optional auth hook

const room = new RoomSession('private-room', {
  persistence: adapter,
  auth: async ({ roomId, conn }) => {
    // return false to reject addConnection
    return true
  },
})

Example apps

• Full stack: examples/collab-demo
• Minimal Cloudflare DO: examples/cloudflare

Develop

bun run build
bun run typecheck