@veltdev/spreadjs-crdt

Vanilla JavaScript CRDT wrapper for MESCIUS SpreadJS workbooks, powered by Velt.

Install

npm install @veltdev/spreadjs-crdt @mescius/spread-sheets @veltdev/client

SpreadJS is a commercial product. Configure your MESCIUS license or trial key in the host application before creating the workbook.

Usage

import GC from '@mescius/spread-sheets';
import '@mescius/spread-sheets/styles/gc.spread.sheets.css';
import { createCollaboration } from '@veltdev/spreadjs-crdt';

const workbook = new GC.Spread.Sheets.Workbook(document.querySelector('#editor'), {
  sheetCount: 1,
});

const manager = await createCollaboration({
  editorId: 'spreadjs-document-id',
  veltClient,
  workbook,
  events: GC.Spread.Sheets.Events,
  serializationOptions: { includeBindingSource: true },
});

manager.setCellValue(0, 0, 'Shared value');
manager.highlightSelection('#fde047');
await manager.saveVersion('Checkpoint');

Collaboration is fully automatic once the manager is attached: edits, formatting, sheet changes, and selections made through the SpreadJS UI sync out of the box, and remote users' changes and selection overlays are applied and rendered automatically. The API below is optional programmatic control on top of that.

What It Syncs

• Workbook JSON snapshots from workbook.toJSON().
• Remote workbook state through workbook.fromJSON().
• Cell edits, sheet changes, formatting snapshots, and force resets.
• Local and remote selections through Velt awareness.
• Version save/list/restore through the Velt Store.

Important Model

This package uses a Velt Store<WorkbookState> with type: "map" and contentKey: "workbook".

The binding is snapshot-based, not operation-level spreadsheet CRDT merging. Concurrent overlapping edits converge by the latest accepted workbook snapshot. Use application-level policy for workflows that require cell-level conflict resolution.

API

• createCollaboration(config)
• new CollaborationManager(config)
• attachWorkbook(workbook, options)
• flushWorkbookToStore(reason?, immediate?)
• setCellValue(row, col, value, sheetName?)
• getCellValue(row, col, sheetName?)
• addSheet()
• highlightSelection(color?)
• clearSelectionHighlight()
• publishCurrentSelection()
• setLocalSelection(selection)
• getRemoteSelections()
• renderRemoteSelections(container?)
• saveVersion(name)
• getVersions()
• getVersionById(versionId)
• restoreVersion(versionId)
• forceReset(initialContent?)
• destroy()

Docs

See the repository demo/INTEGRATION.md for the full integration guide and Playwright-backed demo.