Electric — Yjs Collaboration | Skills Pool

스킬 파일

Electric — Yjs Collaboration

Set up ElectricProvider for real-time collaborative editing with Yjs via Electric shapes. Covers ElectricProvider configuration, document updates shape with BYTEA parser (parseToDecoder), awareness shape at offset='now', LocalStorageResumeStateProvider for reconnection with stableStateVector diff, debounceMs for batching writes, sendUrl PUT endpoint, required Postgres schema (ydoc_update and ydoc_awareness tables), CORS header exposure, and sendErrorRetryHandler. Load when implementing collaborative editing with Yjs and Electric.

electric-sql10,092 스타2026. 3. 6.

직업
카테고리: IDE 플러그인

스킬 내용

This skill builds on electric-shapes. Read it first for ShapeStream configuration.

Electric — Yjs Collaboration

Setup

1. Create Postgres tables

CREATE TABLE ydoc_update (
  id SERIAL PRIMARY KEY,
  room TEXT NOT NULL,
  update BYTEA NOT NULL
);

CREATE TABLE ydoc_awareness (
  client_id TEXT,
  room TEXT,
  update BYTEA NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (client_id, room)
);

-- Garbage collect stale awareness entries
CREATE OR REPLACE FUNCTION gc_awareness_timeouts()
RETURNS TRIGGER AS $$
BEGIN
  DELETE FROM ydoc_awareness
  WHERE updated_at < (CURRENT_TIMESTAMP - INTERVAL '30 seconds')
    AND room = NEW.room;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER gc_awareness
  AFTER INSERT OR UPDATE ON ydoc_awareness
  FOR EACH ROW EXECUTE FUNCTION gc_awareness_timeouts();

2. Create server endpoint for receiving updates

관련 스킬

// PUT /api/yjs/update — receives binary Yjs update
app.put('/api/yjs/update', async (req, res) => {
  const body = Buffer.from(await req.arrayBuffer())
  await db.query('INSERT INTO ydoc_update (room, update) VALUES ($1, $2)', [
    req.headers['x-room-id'],
    body,
  ])
  res.status(200).end()
})

import * as Y from 'yjs'
import {
  ElectricProvider,
  LocalStorageResumeStateProvider,
  parseToDecoder,
} from '@electric-sql/y-electric'

const ydoc = new Y.Doc()
const roomId = 'my-document'

const resumeProvider = new LocalStorageResumeStateProvider(roomId)

const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: {
    shape: {
      url: `/api/yjs/doc-shape?room=${roomId}`,
      parser: parseToDecoder,
    },
    sendUrl: '/api/yjs/update',
    getUpdateFromRow: (row) => row.update,
  },
  awarenessUpdates: {
    shape: {
      url: `/api/yjs/awareness-shape?room=${roomId}`,
      parser: parseToDecoder,
      offset: 'now', // Only live awareness, no historical backfill
    },
    sendUrl: '/api/yjs/awareness',
    protocol: provider.awareness,
    getUpdateFromRow: (row) => row.update,
  },
  resumeState: resumeProvider.load(),
  debounceMs: 100, // Batch rapid edits
})

// Persist resume state for efficient reconnection
resumeProvider.subscribeToResumeState(provider)

// Proxy must expose Electric headers
const corsHeaders = {
  'Access-Control-Expose-Headers':
    'electric-offset, electric-handle, electric-schema, electric-cursor',
}

// On construction, pass stored resume state
const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: { shape: shapeOpts, sendUrl: '/api/yjs/update' },
  resumeState: resumeProvider.load(),
})

// Subscribe to persist updates
const unsub = resumeProvider.subscribeToResumeState(provider)

// Clean up
provider.destroy()
unsub()

provider.on('status', ({ status }) => {
  // 'connecting' | 'connected' | 'disconnected'
  console.log('Yjs sync status:', status)
})

provider.on('sync', (synced: boolean) => {
  console.log('Document synced:', synced)
})

// Manual disconnect/reconnect
provider.disconnect()
provider.connect()

const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: {
    shape: { url: '/api/yjs/doc-shape', parser: parseToDecoder },
    sendUrl: '/api/yjs/update',
    getUpdateFromRow: (row) => row.update,
  },
})

const resumeProvider = new LocalStorageResumeStateProvider('my-doc')
const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: {
    shape: { url: '/api/yjs/doc-shape', parser: parseToDecoder },
    sendUrl: '/api/yjs/update',
    getUpdateFromRow: (row) => row.update,
  },
  resumeState: resumeProvider.load(),
})
resumeProvider.subscribeToResumeState(provider)

documentUpdates: {
  shape: { url: '/api/yjs/doc-shape' },
  sendUrl: '/api/yjs/update',
  getUpdateFromRow: (row) => row.update,
}

import { parseToDecoder } from '@electric-sql/y-electric'

documentUpdates: {
  shape: {
    url: '/api/yjs/doc-shape',
    parser: parseToDecoder,
  },
  sendUrl: '/api/yjs/update',
  getUpdateFromRow: (row) => row.update,
}

const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: { shape: shapeOpts, sendUrl: '/api/yjs/update' },
  // Default debounceMs = 0: every keystroke sends a PUT
})

const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: { shape: shapeOpts, sendUrl: '/api/yjs/update' },
  debounceMs: 100,
})