@veltdev/spreadjs-crdt-react

React hook, drop-in component, and context provider for collaborative MESCIUS SpreadJS workbooks, powered by Velt. Wraps @veltdev/spreadjs-crdt with React lifecycle management.

Install

npm install @veltdev/spreadjs-crdt-react @veltdev/spreadjs-crdt @veltdev/react @veltdev/types @mescius/spread-sheets react react-dom

SpreadJS is a commercial product. Configure your MESCIUS license or trial key in the host application (or pass it through the component's licenseKey prop) before creating the workbook.

Usage

import { VeltProvider } from '@veltdev/react';
import { SpreadJSCrdtWorkbook } from '@veltdev/spreadjs-crdt-react';

export function App() {
  return (
    <VeltProvider apiKey="YOUR_API_KEY">
      <SpreadJSCrdtWorkbook
        documentId="finance-workbook"
        className="spread-host"
        style={{ width: '100%', height: 640 }}
        debounceMs={120}
      />
    </VeltProvider>
  );
}

Collaboration is fully automatic once the component (or hook) is mounted: 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 delegates to @veltdev/spreadjs-crdt, which 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

React surface:

• useCollaboration(config) — hook returning { manager, workbook, isLoading, synced, isSynced, status, error, versions, remoteSelections, stats } plus delegate methods (attachWorkbook, detachWorkbook, forceReset, flushWorkbookToStore, publishCurrentSelection, renderRemoteSelections, setCellValue, getCellValue, addSheet, highlightSelection, clearSelectionHighlight, saveVersion, getVersions, refreshVersions, restoreVersion, setStateFromVersion, destroy).
• SpreadJSCrdtWorkbook — drop-in component that creates the SpreadJS workbook host, applies the license key, and runs the hook. Accepts documentId/editorId, licenseKey, workbookOptions, prepareInitialContent, onWorkbookReady, onManagerReady, onStatusChange, and a children render prop receiving the hook value.
• SpreadJSCrdtProvider / useCollaborationContext() — context provider that runs the hook once and shares its result with descendants. useCollaborationContext() returns null outside a provider (it never throws).

Re-exported from @veltdev/spreadjs-crdt:

• CollaborationManager, createCollaboration
• Content helpers: cloneJson, createSelectionState, createWorkbookState, hasWorkbookJson, isWorkbookState, normalizeRanges, stableStringify
• Workbook and awareness types (WorkbookState, WorkbookJson, RemoteSelection, SpreadRange, and more)

Docs

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