SpreadJS Workbooks

The @veltdev/spreadjs-crdt-react and @veltdev/spreadjs-crdt libraries enable real-time collaborative workbook editing with MESCIUS SpreadJS. The collaboration engine serializes workbook state into a Velt CRDT Store backed by Yjs.

Prerequisites

Node.js (v14 or higher)
A Mescius SpreadJS license for production use, as required by Mescius
A Velt account with an API key (sign up)
React (v18 or higher) when using the React wrapper
Optional: TypeScript for type safety

Setup

Step 1: Install Dependencies

React / Next.js
Other Frameworks

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

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

Import the SpreadJS stylesheet in your application entry point:

import '@mescius/spread-sheets/styles/gc.spread.sheets.excel2013white.css';

The current wrapper peer range targets @mescius/spread-sheets@^19.1.3. Use the peer-compatible version, configure a production license before constructing a workbook, and do not commit production license keys to public source control.

Step 2: Create the Workbook

Create a host with stable dimensions, apply the license, and construct the workbook before creating collaboration. The drop-in React component performs these steps internally; React hook and Other Frameworks integrations own the workbook themselves.

<div id="spread-host" class="spread-host"></div>

import GC from '@mescius/spread-sheets';

GC.Spread.Sheets.LicenseKey = 'YOUR_SPREADJS_LICENSE_KEY';

const host = document.querySelector<HTMLDivElement>('#spread-host')!;
const workbook = new GC.Spread.Sheets.Workbook(host, {
  sheetCount: 2,
  tabEditable: true,
});

.spread-host {
  height: 640px;
  min-height: 480px;
  position: relative;
  width: 100%;
}

Do not create a workbook while its host is display: none, recreate the host while collaboration is active, or remove it before the manager has detached its event handlers and overlays.

Step 3: Setup Velt

React applications initialize Velt at the app root while the workbook component mounts. Other Frameworks integrations initialize Velt after constructing the workbook. In both cases, authenticate the user and set a stable document before creating collaboration. Follow the Velt Setup Docs for the production token endpoint used by authProvider.

React / Next.js
Other Frameworks

import { useEffect, useState } from 'react';
import {
  VeltProvider,
  useCurrentUser,
  useSetDocuments,
} from '@veltdev/react';

const DOCUMENT_ID = 'forecast-2026';
const USER = {
  userId: 'ada',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  organizationId: 'my-org-id',
};

const authProvider = {
  user: USER,
  retryConfig: { retryCount: 3, retryDelay: 1000 },
  generateToken: async () => {
    const response = await fetch('/api/velt/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(USER),
    });
    const { token } = await response.json();
    return token;
  },
};

function DocumentScope() {
  const user = useCurrentUser();
  const { setDocuments } = useSetDocuments();
  const [documentReady, setDocumentReady] = useState(false);

  useEffect(() => {
    if (!user) {
      setDocumentReady(false);
      return;
    }
    setDocuments([{
      id: DOCUMENT_ID,
      metadata: { documentName: 'Forecast 2026' },
    }]);
    setDocumentReady(true);
  }, [user, setDocuments]);

  return user && documentReady
    ? <ForecastWorkbook />
    : <p>Preparing collaboration...</p>;
}

<VeltProvider apiKey="YOUR_API_KEY" authProvider={authProvider}>
  <DocumentScope />
</VeltProvider>

import { initVelt } from '@veltdev/client';

const DOCUMENT_ID = 'forecast-2026';
const client = await initVelt('YOUR_API_KEY');

await client.identify({
  userId: 'ada',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  organizationId: 'my-org-id',
});

await client.setDocument(DOCUMENT_ID, {
  documentName: 'Forecast 2026',
});

let resolveVeltReady!: () => void;
const veltReady = new Promise<void>((resolve) => {
  resolveVeltReady = resolve;
});
const initSubscription = client.getVeltInitState().subscribe((isReady) => {
  if (isReady) resolveVeltReady();
});
await veltReady;
initSubscription.unsubscribe();

Step 4: Initialize Collaborative Workbook

React Component
React Hook
Other Frameworks

SpreadJSCrdtWorkbook creates one workbook per mount and connects it to the CRDT manager:

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

function ForecastWorkbook() {
  return (
    <SpreadJSCrdtWorkbook
      documentId="forecast-2026"
      licenseKey="YOUR_SPREADJS_LICENSE_KEY"
      className="spread-host"
      workbookOptions={{ sheetCount: 2, tabEditable: true }}
      prepareInitialContent={(workbook: SpreadWorkbook) => {
        const sheet = workbook.getActiveSheet?.();
        sheet?.setValue?.(0, 0, 'Revenue forecast');
        return workbook.toJSON?.({ includeBindingSource: true }) ?? null;
      }}
      serializationOptions={{ includeBindingSource: true }}
      debounceMs={120}
      onError={(error) => console.error('Collaboration error:', error)}
    />
  );
}

The wrapper’s licenseKey prop is optional. When provided, the wrapper applies it before creating the workbook. You can omit the prop if your application configures the license elsewhere, but Mescius licensing requirements still apply to production deployments.

Use useCollaboration() when your application creates the workbook:

import GC from '@mescius/spread-sheets';
import { useEffect, useRef, useState } from 'react';
import { useCollaboration } from '@veltdev/spreadjs-crdt-react';
import type { SpreadWorkbook } from '@veltdev/spreadjs-crdt-react';

function HookWorkbook() {
  const hostRef = useRef<HTMLDivElement | null>(null);
  const workbookRef = useRef<SpreadWorkbook | null>(null);
  const [workbook, setWorkbook] = useState<SpreadWorkbook | null>(null);

  useEffect(() => {
    if (!hostRef.current) return;
    GC.Spread.Sheets.LicenseKey = 'YOUR_SPREADJS_LICENSE_KEY';
    const created = new GC.Spread.Sheets.Workbook(hostRef.current, { sheetCount: 2 });
    workbookRef.current = created;
    setWorkbook(created);
  }, []);

  const collaboration = useCollaboration({
    editorId: 'forecast-2026',
    workbook,
    events: GC.Spread.Sheets.Events,
    serializationOptions: { includeBindingSource: true },
    debounceMs: 120,
  });

  useEffect(() => {
    return () => {
      collaboration.destroy();
      workbookRef.current?.destroy?.();
      workbookRef.current = null;
    };
  }, [collaboration.destroy]);

  return (
    <>
      <span>{collaboration.status}</span>
      <div ref={hostRef} className="spread-host" data-spreadjs-host />
    </>
  );
}

Add data-spreadjs-host to an application-owned host; the drop-in component adds this marker automatically. Only identity-bearing inputs (veltClient, editorId, workbook, and initializeWithoutWorkbook) reinitialize the manager. Options objects and callbacks are captured at initialization and do not require memoization.

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

GC.Spread.Sheets.LicenseKey = 'YOUR_SPREADJS_LICENSE_KEY';
const host = document.querySelector<HTMLDivElement>('#spread-host')!;
const workbook = new GC.Spread.Sheets.Workbook(host, {
  sheetCount: 2,
  tabEditable: true,
});

const client = await initVelt('YOUR_API_KEY');
await client.identify({
  userId: 'ada',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  organizationId: 'my-org-id',
});
await client.setDocument('forecast-2026', {
  documentName: 'Forecast 2026',
});

let resolveVeltReady!: () => void;
const veltReady = new Promise<void>((resolve) => {
  resolveVeltReady = resolve;
});
const initSubscription = client.getVeltInitState().subscribe((isReady) => {
  if (isReady) resolveVeltReady();
});
await veltReady;
initSubscription.unsubscribe();

const manager = await createCollaboration({
  editorId: 'forecast-2026',
  veltClient: client,
  workbook,
  events: GC.Spread.Sheets.Events,
  initialContent: workbook.toJSON({ includeBindingSource: true }),
  serializationOptions: { includeBindingSource: true },
  deserializationOptions: { doNotRecalculateAfterLoad: false },
  debounceMs: 120,
  onError: (error) => console.error('SpreadJS collaboration:', error),
});

const offStatus = manager.onStatusChange(console.log);
const offSynced = manager.onSynced(console.log);
const offSelections = manager.onRemoteSelectionsChange((selections) => {
  console.log('Remote selections:', selections);
  manager.renderRemoteSelections();
});

// Route or page teardown:
offSelections();
offSynced();
offStatus();
manager.destroy();
workbook.destroy();

The React hook checks Velt initialization, an authenticated user, a non-empty editor ID, and a workbook unless initializeWithoutWorkbook is enabled. Passing workbook to the factory or hook attaches it automatically; do not call attachWorkbook(workbook) again on the same initialization path.

import {
  SpreadJSCrdtProvider,
  useCollaborationContext,
} from '@veltdev/spreadjs-crdt-react';

function Toolbar() {
  const collaboration = useCollaborationContext();
  return (
    <button onClick={() => collaboration?.saveVersion('Checkpoint')}>
      Save version
    </button>
  );
}

<SpreadJSCrdtProvider config={{ editorId: 'forecast-2026', workbook }}>
  <Toolbar />
</SpreadJSCrdtProvider>

useCollaborationContext() returns null outside the provider instead of throwing.

Step 5: Attach a Workbook Later (Optional)

React / Next.js
Other Frameworks

Initialize the manager before route data or a workbook exists:

const collaboration = useCollaboration({
  editorId: 'forecast-2026',
  initializeWithoutWorkbook: true,
});

useEffect(() => {
  if (!workbook) return;
  collaboration.attachWorkbook(workbook, {
    events: GC.Spread.Sheets.Events,
    applyRemoteState: true,
  });
  return () => collaboration.detachWorkbook();
}, [workbook]);

This is an alternative to passing workbook to createCollaboration(). Create the manager without a workbook, create the workbook when its host is ready, and attach it once:

const manager = await createCollaboration({
  editorId: 'forecast-2026',
  veltClient: client,
  events: GC.Spread.Sheets.Events,
});

const workbook = new GC.Spread.Sheets.Workbook(host, { sheetCount: 2 });
manager.attachWorkbook(workbook, {
  events: GC.Spread.Sheets.Events,
  applyRemoteState: true,
});

To replace the workbook, detach it before destroying the old instance:

manager.detachWorkbook();
oldWorkbook.destroy();

const nextWorkbook = new GC.Spread.Sheets.Workbook(nextHost, { sheetCount: 2 });
manager.attachWorkbook(nextWorkbook, {
  events: GC.Spread.Sheets.Events,
  applyRemoteState: true,
});

Do not call attachWorkbook() after already passing that same workbook to the factory. One manager must not remain attached to multiple live workbooks.

Step 6: Status Monitoring (Optional)

React / Next.js
Other Frameworks

const { manager, status, synced, isLoading, error, stats } = collaboration;

useEffect(() => {
  if (!manager) return;
  const offStatus = manager.onStatusChange(console.log);
  const offSynced = manager.onSynced(console.log);
  return () => {
    offStatus();
    offSynced();
  };
}, [manager]);

stats reports initialization, connection state, workbook attachment, Store availability, remote selection count, and the last flush reason.

console.log(manager.initialized, manager.status, manager.synced);
console.log(manager.workbookAttached, manager.getStats());

const offStatus = manager.onStatusChange((status) => {
  console.log('Status:', status);
});
const offSynced = manager.onSynced((synced) => {
  console.log('Synced:', synced);
});

Step 7: Version Management (Optional)

React / Next.js
Other Frameworks

const versionId = await collaboration.saveVersion('Before Q3 changes');
const versions = await collaboration.refreshVersions();
await collaboration.restoreVersion(versionId);

const versionId = await manager.saveVersion('Before Q3 changes');
let versions = await manager.getVersions();

await manager.restoreVersion(versionId);
versions = await manager.getVersions();

The manager serializes the current workbook before saving. Restoring a version applies the shared workbook JSON to all attached clients.

Step 8: Initial Content and Force Reset (Optional)

initialContent accepts raw SpreadJS workbook JSON or a WorkbookState object:

React / Next.js
Other Frameworks

<SpreadJSCrdtWorkbook
  documentId="forecast-2026"
  initialContent={{
    sheets: {
      Sheet1: {
        data: { dataTable: { 0: { 0: { value: 'Forecast' } } } },
      },
    },
  }}
/>

Use the explicit reset method for reset controls:

await collaboration.forceReset(resetWorkbookJson);

const manager = await createCollaboration({
  editorId: 'forecast-2026',
  veltClient: client,
  workbook,
  events: GC.Spread.Sheets.Events,
  initialContent: seedWorkbookJson,
});

await manager.forceReset(resetWorkbookJson);

For a new Store, the manager applies initialContent and then attaches it to the workbook. Existing persisted state wins during normal initialization. forceResetInitialContent resets during manager creation; forceReset() is the explicit runtime reset. Calling forceReset() without an argument uses configured initialContent, or the current workbook JSON when no seed exists.

forceResetInitialContent and forceReset() replace the complete shared workbook snapshot, including existing user changes.

Step 9: Configure Serialization

The wrapper synchronizes complete workbook snapshots rather than individual cell operations:

Local event-driven writes call workbook.toJSON(serializationOptions) after the configured debounce.
Remote Store updates call workbook.fromJSON(json, deserializationOptions) while painting and SpreadJS events are suspended.
Direct helpers flush immediately, and deterministic snapshot signatures suppress echo loops.

const manager = await createCollaboration({
  editorId: 'forecast-2026',
  veltClient: client,
  workbook,
  events: GC.Spread.Sheets.Events,
  initialContent: workbook.toJSON({ includeBindingSource: true }),
  serializationOptions: {
    includeBindingSource: true,
  },
  deserializationOptions: {
    doNotRecalculateAfterLoad: false,
  },
});

Use actual SpreadJS toJSON() output as seed content and keep both option objects stable for a document family. Test formulas, bindings, named styles, formatting, comments, shapes, and workbook size with the options used in production. This is a workbook-level snapshot strategy, not an operation-level cell CRDT. Overlapping edits to the same cell resolve through the latest accepted snapshot; the wrapper does not provide formula conflict resolution, operational locking, JSON compression, or cell-level merge policies.

Step 10: Cell, Sheet, and Formatting Helpers

React / Next.js
Other Frameworks

collaboration.setCellValue(0, 0, 'Pipeline');
const value = collaboration.getCellValue<string>(0, 0);
collaboration.addSheet();
collaboration.highlightSelection('#fff3a3');
collaboration.clearSelectionHighlight();
await collaboration.flushWorkbookToStore('toolbar-action', true);

manager.setCellValue(0, 0, 'Pipeline');
const value = manager.getCellValue(0, 0);
manager.addSheet();
manager.highlightSelection('#fff3a3');
manager.clearSelectionHighlight();
await manager.flushWorkbookToStore('toolbar-action', true);

The helpers call SpreadJS and then synchronize the resulting serialized workbook. Use normal SpreadJS APIs for operations not covered by these conveniences. Rows and columns are zero-based. Direct SpreadJS cell, sheet, and formatting changes are captured through the official event constants; call flushWorkbookToStore() after complex multi-step operations when immediate persistence is required. Cell/value/range changes, active-sheet changes, sheet changes and renames, and selections are included in the event configuration. Highlights use SpreadJS backColor formatting and persist when the selected serialization options include that formatting.

Step 11: Configure Remote Selections (Optional)

React / Next.js
Other Frameworks

collaboration.publishCurrentSelection();
const remoteSelections = collaboration.remoteSelections;
collaboration.renderRemoteSelections();

manager.publishCurrentSelection();

const offSelections = manager.onRemoteSelectionsChange((selections) => {
  console.log('Remote selections:', selections);
  manager.renderRemoteSelections();
});

const remoteSelections = manager.getRemoteSelections();

The manager publishes sheet name, ranges, active cell, and user metadata through Yjs awareness. Selection state is transient and is not stored in workbook versions. Call clearRemoteSelectionOverlays() on the manager when replacing the workbook host or implementing custom overlay cleanup. The manager positions its pointer-transparent overlay inside workbook.getHost() by default and renders only selections for the active sheet. Remote selections on other sheets remain available through awareness. The built-in overlay root uses data-velt-spreadjs-remote-selections. Selection rectangles use data-velt-spreadjs-selection, carets use data-velt-spreadjs-caret, and labels expose the collaborator name through data-velt-spreadjs-cursor-name. These attributes are stable hooks for tests and custom styling.

.velt-spreadjs-selection-label {
  border-radius: 4px;
  color: white;
  font-size: 12px;
  font-weight: 600;
  padding: 2px 6px;
  white-space: nowrap;
}

Step 12: CRDT Event Subscription (Optional)

React / Next.js
Other Frameworks

import { useEffect } from 'react';
import { useVeltClient } from '@veltdev/react';

const { client } = useVeltClient();

useEffect(() => {
  if (!client) return;

  const subscription = client.getCrdtElement().on('updateData').subscribe((event) => {
    if (event) console.log('CRDT update:', event);
  });

  return () => subscription?.unsubscribe?.();
}, [client]);

const crdtSubscription = client
  .getCrdtElement()
  .on('updateData')
  .subscribe((event) => {
    if (event) console.log('CRDT update:', event);
  });

Step 13: Custom Encryption (Optional)

React / Next.js
Other Frameworks

const encryptionProvider = {
  encrypt: async ({ data }) => data.map((n) => n.toString()).join('__'),
  decrypt: async ({ data }) => data.split('__').map((s) => parseInt(s, 10)),
};

<VeltProvider
  apiKey="YOUR_API_KEY"
  authProvider={authProvider}
  encryptionProvider={encryptionProvider}
>
  ...
</VeltProvider>

Configure encryption before creating the collaboration manager:

client.setEncryptionProvider({
  encrypt: async ({ data }) => data.map((n) => n.toString()).join('__'),
  decrypt: async ({ data }) => data.split('__').map((s) => parseInt(s, 10)),
});

Step 14: Error Handling (Optional)

React / Next.js
Other Frameworks

const collaboration = useCollaboration({
  editorId: 'forecast-2026',
  workbook,
  onError: (error) => console.error('SpreadJS collaboration:', error),
});

if (collaboration.error) return <div>{collaboration.error.message}</div>;

const manager = await createCollaboration({
  editorId: 'forecast-2026',
  veltClient: client,
  workbook,
  events: GC.Spread.Sheets.Events,
  onError: (error) => {
    console.error('SpreadJS collaboration:', error);
  },
});

if (!manager.getStore() || !manager.workbookAttached) {
  manager.destroy();
  workbook.destroy();
  throw new Error('SpreadJS collaboration did not initialize');
}

Public methods catch internal failures and return conservative values. Use return values, status, synced, and subscriptions for application control flow.

Step 15: Access Yjs Internals (Advanced)

React / Next.js
Other Frameworks

const doc = collaboration.manager?.getDoc();
const map = collaboration.manager?.getMap();
const store = collaboration.manager?.getStore();
const provider = collaboration.manager?.getProvider();
const awareness = collaboration.manager?.getAwareness();
const workbookState = collaboration.manager?.getWorkbookState();

const doc = manager.getDoc();
const map = manager.getMap();
const store = manager.getStore();
const provider = manager.getProvider();
const awareness = manager.getAwareness();
const workbookState = manager.getWorkbookState();
const workbookJson = manager.getWorkbookJson();

The manager supplies these Yjs and provider objects. Do not create a second document, provider, or awareness instance, and prefer wrapper methods because direct Yjs mutations bypass workbook application safeguards and snapshot signature tracking.

Step 16: Cleanup

React / Next.js
Other Frameworks

The hook destroys the manager automatically. SpreadJSCrdtWorkbook also destroys the workbook it creates. When using the hook with an application-owned workbook, destroy collaboration before the workbook:

useEffect(() => {
  return () => {
    collaboration.destroy();
    workbookRef.current?.destroy?.();
    workbookRef.current = null;
  };
}, [collaboration.destroy]);

Unsubscribe callbacks, clear or detach overlays, destroy the manager, destroy the workbook, and remove the host last:

crdtSubscription.unsubscribe();
offSelections();
offSynced();
offStatus();

manager.clearRemoteSelectionOverlays();
manager.destroy();
workbook.destroy();
host.remove();

The manager’s destroy() also detaches the workbook and clears its registered workbook and sheet event handlers.

Notes

Snapshot model: SpreadJS workbook JSON is synchronized as a structured snapshot, not as independent CRDT cells.
Store identity: The manager uses a map Store with content key workbook and source metadata spreadjs.
Debounced serialization: Local workbook events are batched before toJSON() and Store writes; the default is 120 ms.
Serialization parity: Use compatible serializationOptions and deserializationOptions across clients.
Workbook ownership: The component creates and destroys a workbook; the hook accepts an application-owned workbook.
Awareness: Cell selections are transient presence state and do not appear in saved versions.
Unique editorId: Collaborators must share the same Velt document and editor ID.
Persistence: Reopening the same editorId replays the persisted workbook snapshot; unrelated workbooks need different IDs.
Required events: Pass GC.Spread.Sheets.Events so workbook, active-sheet, cell, range, value, sheet-name, and selection changes use the official event constants.
One attachment path: Passing workbook during creation attaches it automatically. Use attachWorkbook() only when the manager was initialized without that workbook or when replacing a detached workbook.
Lifecycle: Destroy the manager before destroying the application-owned workbook or removing its host.
One Yjs instance: Deduplicate yjs and y-protocols so the wrapper and application share compatible Yjs constructors.
Behavioral boundary: Snapshot synchronization does not provide cell-operation merging, formula conflict resolution, operational locking, JSON compression, or application authorization.
Production authentication: Use a server-backed Velt authProvider; never expose privileged server tokens in browser code.

Testing and Debugging

To test collaboration:

Open the same Velt document and SpreadJS editorId as two different users.
Change cell values, formulas, formatting, sheet names, and selections.
Verify remote workbook state, awareness overlays, version restore, and persistence after reload.
Test large workbooks with the intended serialization options and debounce interval.

Common issues:

Blank workbook host: Give the host an explicit height and verify the SpreadJS license.
Workbook remains loading: Confirm Velt auth is ready and the workbook is attached, or use initializeWithoutWorkbook.
Changes are missing: Pass GC.Spread.Sheets.Events and compatible serialization options.
Conflicting cell edits overwrite each other: The adapter synchronizes complete workbook snapshots; add a product-level conflict policy for high-risk concurrent operations.
Repeated full resets: Disable forceResetInitialContent during normal loads.
Overlay drift: Clear and rerender remote selections after sheet or viewport changes.

Use the VeltCrdtStoreMap debugging interface to inspect serialized workbook state and provider status.

Complete Example

React / Next.js
Other Frameworks

Complete App.tsx

import { useEffect, useMemo, useState } from 'react';
import '@mescius/spread-sheets/styles/gc.spread.sheets.excel2013white.css';
import {
  VeltProvider,
  useCurrentUser,
  useSetDocuments,
} from '@veltdev/react';
import {
  SpreadJSCrdtWorkbook,
  type SpreadWorkbook,
  type SpreadJSCollaborationManager,
} from '@veltdev/spreadjs-crdt-react';

const DOCUMENT_ID = 'forecast-2026';
const USER = {
  userId: 'ada',
  organizationId: 'my-org-id',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
};

function ForecastWorkbook() {
  const user = useCurrentUser();
  const { setDocuments } = useSetDocuments();
  const [manager, setManager] = useState<SpreadJSCollaborationManager | null>(null);
  const [versionName, setVersionName] = useState('');
  const [documentReady, setDocumentReady] = useState(false);

  useEffect(() => {
    if (!user) {
      setDocumentReady(false);
      return;
    }
    setDocuments([{
      id: DOCUMENT_ID,
      metadata: { documentName: 'Forecast 2026' },
    }]);
    setDocumentReady(true);
  }, [user, setDocuments]);

  if (!user || !documentReady) return <p>Preparing collaboration...</p>;

  const saveVersion = async () => {
    if (!manager || !versionName.trim()) return;
    await manager.saveVersion(versionName.trim());
    setVersionName('');
  };

  return (
    <main>
      <input value={versionName} onChange={(event) => setVersionName(event.target.value)} />
      <button onClick={saveVersion}>Save version</button>
      <SpreadJSCrdtWorkbook
        documentId={DOCUMENT_ID}
        licenseKey="YOUR_SPREADJS_LICENSE_KEY"
        className="spread-host"
        workbookOptions={{ sheetCount: 2, tabEditable: true }}
        prepareInitialContent={(workbook: SpreadWorkbook) => {
          const sheet = workbook.getActiveSheet?.();
          sheet?.setValue?.(0, 0, 'Forecast');
          sheet?.setValue?.(0, 1, 'Q1');
          return workbook.toJSON?.({ includeBindingSource: true }) ?? null;
        }}
        serializationOptions={{ includeBindingSource: true }}
        onManagerReady={setManager}
        onStatusChange={(status) => console.log('Status:', status)}
        onError={console.error}
      />
    </main>
  );
}

export default function App() {
  const authProvider = useMemo(() => ({
    user: USER,
    retryConfig: { retryCount: 3, retryDelay: 1000 },
    generateToken: async () => {
      const response = await fetch('/api/velt/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(USER),
      });
      const { token } = await response.json();
      return token;
    },
  }), []);

  return (
    <VeltProvider apiKey="YOUR_VELT_API_KEY" authProvider={authProvider}>
      <ForecastWorkbook />
    </VeltProvider>
  );
}

Complete styles.css

.spread-host {
  width: 100%;
  height: 640px;
  min-height: 480px;
}

Complete index.html

<p>Status: <span id="status">connecting</span></p>
<p>Synced: <span id="synced">No</span></p>
<div id="spread-host" class="spread-host"></div>

Complete app.ts

import GC from '@mescius/spread-sheets';
import '@mescius/spread-sheets/styles/gc.spread.sheets.excel2013white.css';
import { initVelt } from '@veltdev/client';
import {
  createCollaboration,
  type CollaborationManager,
} from '@veltdev/spreadjs-crdt';
import './styles.css';

const DOCUMENT_ID = 'forecast-2026';

GC.Spread.Sheets.LicenseKey = 'YOUR_SPREADJS_LICENSE_KEY';

const host = document.querySelector<HTMLDivElement>('#spread-host')!;
const workbook = new GC.Spread.Sheets.Workbook(host, {
  sheetCount: 2,
  tabEditable: true,
});

const seedSheet = workbook.getActiveSheet();
seedSheet.setValue(0, 0, 'Forecast');
seedSheet.setValue(0, 1, 'Q1');
const seedWorkbookJson = workbook.toJSON({
  includeBindingSource: true,
});

const client = await initVelt('YOUR_VELT_API_KEY');
await client.identify({
  userId: 'ada',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  organizationId: 'my-org-id',
});
await client.setDocument(DOCUMENT_ID, {
  documentName: 'Forecast 2026',
});

let resolveVeltReady!: () => void;
const veltReady = new Promise<void>((resolve) => {
  resolveVeltReady = resolve;
});
const initSubscription = client.getVeltInitState().subscribe((isReady) => {
  if (isReady) resolveVeltReady();
});
await veltReady;
initSubscription.unsubscribe();

const manager: CollaborationManager = await createCollaboration({
  editorId: DOCUMENT_ID,
  veltClient: client,
  workbook,
  events: GC.Spread.Sheets.Events,
  initialContent: seedWorkbookJson,
  serializationOptions: {
    includeBindingSource: true,
  },
  deserializationOptions: {
    doNotRecalculateAfterLoad: false,
  },
  debounceMs: 120,
  userColor: '#2563eb',
  onError: (error) => console.error('SpreadJS collaboration:', error),
});

const offStatus = manager.onStatusChange((status) => {
  document.querySelector('#status')!.textContent = status;
});
const offSynced = manager.onSynced((synced) => {
  document.querySelector('#synced')!.textContent = synced ? 'Yes' : 'No';
});
const offSelections = manager.onRemoteSelectionsChange((selections) => {
  console.log('Remote selections:', selections);
  manager.renderRemoteSelections();
});
const crdtSubscription = client
  .getCrdtElement()
  .on('updateData')
  .subscribe((event) => {
    if (event) console.log('CRDT update:', event);
  });

manager.setCellValue(1, 0, 125000);
manager.publishCurrentSelection();
manager.renderRemoteSelections();

const versionId = await manager.saveVersion('Before Q3 changes');
console.log('Saved version:', versionId, await manager.getVersions());

window.addEventListener('beforeunload', () => {
  crdtSubscription.unsubscribe();
  offSelections();
  offSynced();
  offStatus();

  manager.clearRemoteSelectionOverlays();
  manager.destroy();
  workbook.destroy();
});

Complete styles.css

.spread-host {
  height: 640px;
  min-height: 480px;
  position: relative;
  width: 100%;
}

.velt-spreadjs-selection-label {
  border-radius: 4px;
  color: white;
  font-size: 12px;
  font-weight: 600;
  padding: 2px 6px;
  white-space: nowrap;
}

How It Works

The application loads SpreadJS styles, applies its license, sizes the host, and creates the workbook before the normal collaboration path.
React uses an authenticated VeltProvider; other frameworks initialize one Velt client, authenticate the user, and set the document before creating the manager.
Passing the workbook and GC.Spread.Sheets.Events attaches official workbook and active-sheet listeners during manager initialization.
Local events serialize workbook.toJSON() into a versioned WorkbookState; remote state is applied with workbook.fromJSON() while painting and events are suspended.
Awareness carries transient sheet ranges and active-cell metadata for pointer-transparent remote overlays.
Versions, persistence, and reset operate on the complete serialized workbook snapshot.

APIs

React: SpreadJSCrdtWorkbook

Prop	Description
`editorId` / `documentId`	Stable shared workbook ID.
`licenseKey`	Optional SpreadJS license key applied before workbook construction.
`workbookOptions`	Options for `new Workbook()`.
`initialContent` / `prepareInitialContent`	First-load workbook state.
`serializationOptions` / `deserializationOptions`	SpreadJS JSON options.
`debounceMs`	Workbook flush debounce.
`userColor`	Local awareness color.
`onWorkbookReady`, `onManagerReady`, `onStatusChange`, `onError`	Lifecycle callbacks.
`children`	Render function receiving hook state.

React: useCollaboration()

The hook returns manager, workbook, lifecycle state, versions, remote selections, statistics, attachment helpers, reset/flush helpers, cell/sheet helpers, selection helpers, and destroy().

Other Frameworks: createCollaboration()

import { createCollaboration } from '@veltdev/spreadjs-crdt';

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  veltClient: client,
  workbook,
  events: GC.Spread.Sheets.Events,
  initialContent: seedWorkbookJson,
  serializationOptions: { includeBindingSource: true },
  deserializationOptions: { doNotRecalculateAfterLoad: false },
  debounceMs: 120,
  userColor: '#2563eb',
  onError: console.error,
});

Config	Type	Required	Description
`editorId`	`string`	Yes	Stable workbook ID shared by collaborators.
`veltClient`	`Velt`	Yes	Initialized, authenticated client with a current document.
`workbook`	`SpreadWorkbook \| null`	Normal path	Application-owned workbook to attach automatically.
`events`	`SpreadJSEvents`	Recommended	Pass `GC.Spread.Sheets.Events` for official event names.
`initialContent`	`WorkbookJson \| WorkbookState \| null`	No	New-document workbook seed.
`serializationOptions`	`Record<string, any>`	No	Options passed to `workbook.toJSON()`.
`deserializationOptions`	`Record<string, any>`	No	Options passed to `workbook.fromJSON()`.
`debounceMs`	`number`	No	Event-driven snapshot debounce; default is 120 ms.
`forceResetInitialContent`	`boolean`	No	Replaces existing shared workbook state during initialization.
`userColor`	`string`	No	Local awareness overlay color.
`onError`	`(error: Error) => void`	No	Receives non-fatal integration errors.

Omit workbook only for the documented attach-later lifecycle. Never pass it here and then attach the same instance again.

CollaborationManager Methods

Method group	Methods
Lifecycle	`initialize()`, `destroy()`, `attachWorkbook()`, `detachWorkbook()`
Status	`initialized`, `synced`, `status`, `workbookAttached`, `onStatusChange()`, `onSynced()`, `getStats()`
Workbook state	`getWorkbook()`, `getWorkbookState()`, `getWorkbookJson()`, `flushWorkbookToStore()`, `forceReset()`
Cells and sheets	`setCellValue()`, `getCellValue()`, `addSheet()`, `highlightSelection()`, `clearSelectionHighlight()`
Awareness	`publishCurrentSelection()`, `setLocalSelection()`, `getCurrentSelection()`, `getRemoteSelections()`, `onRemoteSelectionsChange()`, `renderRemoteSelections()`, `clearRemoteSelectionOverlays()`
Versions	`saveVersion()`, `getVersions()`, `getVersionById()`, `restoreVersion()`, `setStateFromVersion()`
Internals	`getDoc()`, `getMap()`, `getProvider()`, `getAwareness()`, `getStore()`

Exported Types and Helpers

UseCollaborationConfig / UseSpreadJSCrdtConfig, UseCollaborationReturn / SpreadJSCrdtHookResult
SpreadJSCrdtWorkbookProps, SpreadJSCrdtProviderProps, SpreadJSCollaborationManager
SpreadWorkbook, SpreadWorksheet, WorkbookJson, WorkbookState, WorkbookStore
AwarenessSelection, RemoteSelection, SpreadRange, CollaborationStats
cloneJson(), stableStringify(), createWorkbookState(), createSelectionState()
isWorkbookState(), hasWorkbookJson(), normalizeRanges()

​Prerequisites

​Setup

​Step 1: Install Dependencies

​Step 2: Create the Workbook

​Step 3: Setup Velt

​Step 4: Initialize Collaborative Workbook

​Share collaboration through React context (optional)

​Step 5: Attach a Workbook Later (Optional)

​Step 6: Status Monitoring (Optional)

​Step 7: Version Management (Optional)

​Step 8: Initial Content and Force Reset (Optional)

​Step 9: Configure Serialization

​Step 10: Cell, Sheet, and Formatting Helpers

​Step 11: Configure Remote Selections (Optional)

​Step 12: CRDT Event Subscription (Optional)

​Step 13: Custom Encryption (Optional)

​Step 14: Error Handling (Optional)

​Step 15: Access Yjs Internals (Advanced)

​Step 16: Cleanup

​Notes

​Testing and Debugging

​Complete Example

​How It Works

​APIs

​React: SpreadJSCrdtWorkbook

​React: useCollaboration()

​Other Frameworks: createCollaboration()

​CollaborationManager Methods

​Exported Types and Helpers

Prerequisites

Setup

Step 1: Install Dependencies

Step 2: Create the Workbook

Step 3: Setup Velt

Step 4: Initialize Collaborative Workbook

Share collaboration through React context (optional)

Step 5: Attach a Workbook Later (Optional)

Step 6: Status Monitoring (Optional)

Step 7: Version Management (Optional)

Step 8: Initial Content and Force Reset (Optional)

Step 9: Configure Serialization

Step 10: Cell, Sheet, and Formatting Helpers

Step 11: Configure Remote Selections (Optional)

Step 12: CRDT Event Subscription (Optional)

Step 13: Custom Encryption (Optional)

Step 14: Error Handling (Optional)

Step 15: Access Yjs Internals (Advanced)

Step 16: Cleanup

Notes

Testing and Debugging

Complete Example

How It Works

APIs

React: SpreadJSCrdtWorkbook

React: useCollaboration()

Other Frameworks: createCollaboration()

CollaborationManager Methods

Exported Types and Helpers