Monaco Editor

The @veltdev/monaco-crdt-react and @veltdev/monaco-crdt libraries enable real-time collaborative editing in Monaco. The collaboration engine is built on Yjs, y-monaco, and the Velt SDK.

Prerequisites

Node.js (v14 or higher)
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/monaco-crdt-react @veltdev/monaco-crdt @veltdev/react @veltdev/types @monaco-editor/react monaco-editor y-monaco yjs

npm install @veltdev/monaco-crdt @veltdev/client monaco-editor y-monaco yjs

Ensure your application resolves one copy of yjs, y-protocols, and monaco-editor. For Vite projects, deduplicate them explicitly:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    dedupe: ['yjs', 'y-protocols', 'monaco-editor'],
  },
});

Step 2: Setup Velt

Initialize Velt, authenticate a user, and set a stable document context before collaboration starts. Follow the Velt Setup Docs for the production token endpoint used by authProvider.

React / Next.js
Other Frameworks

Wrap the app with an authenticated VeltProvider, then set the document after the current user is available. Keep the document hook unconditional and gate the effect:

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

const DOCUMENT_ID = 'code-file-123';
const USER = {
  userId: 'user-1',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  organizationId: 'org-1',
};

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 CollaborationScope() {
  const user = useCurrentUser();
  const { setDocuments } = useSetDocuments();
  const [documentReady, setDocumentReady] = useState(false);

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

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

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

Initialize one client, authenticate the user, set the document, and wait for Velt readiness before creating Monaco:

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

const DOCUMENT_ID = 'code-file-123';
const client = await initVelt('YOUR_API_KEY');

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

await client.setDocument(DOCUMENT_ID, {
  documentName: 'Code File 123',
});

const initSubscription = client.getVeltInitState().subscribe((isReady) => {
  if (isReady) void initializeMonaco(client);
});

Every collaborator who should edit the same file must use the same Velt document ID and editorId.

Step 3: Initialize Collaborative Editor

Pass an editorId to uniquely identify the shared Monaco model.
Do not pass React wrapper value or defaultValue, and do not seed a direct Monaco editor with non-empty local text. The CRDT-backed model owns shared content.
Pass initialContent as plain text for a brand-new shared document.

React Component
React Hook
Other Frameworks

MonacoCrdtEditor is the simplest integration. It creates Monaco, binds its model to Y.Text, and manages collaboration cleanup.

import { MonacoCrdtEditor } from '@veltdev/monaco-crdt-react';

function CollaborativeEditor() {
  return (
    <MonacoCrdtEditor
      editorId={DOCUMENT_ID}
      language="typescript"
      theme="vs-dark"
      height="500px"
      initialContent={'export const greeting = "Hello";\n'}
      cursorData={{ name: 'Ada', color: '#2563eb' }}
      options={{ minimap: { enabled: false }, wordWrap: 'on' }}
      onError={(error) => console.error('Collaboration error:', error)}
    />
  );
}

Normal @monaco-editor/react props are passed through. The wrapper owns value, defaultValue, and the internal mount handler, but still calls your onMount callback after capturing the editor.

Use useCollaboration() with a custom Monaco setup:

import Editor from '@monaco-editor/react';
import { useCollaboration } from '@veltdev/monaco-crdt-react';

function CollaborativeEditor() {
  const {
    editorRef,
    primitives,
    manager,
    isLoading,
    isSynced,
    status,
    error,
  } = useCollaboration({
    editorId: DOCUMENT_ID,
    initialContent: '// Start writing here\n',
    onError: (err) => console.error('Collaboration error:', err),
  });

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

  return (
    <div>
      <div>Status: {isLoading ? 'loading' : status} | Synced: {isSynced ? 'Yes' : 'No'}</div>
      <Editor
        height="500px"
        language="typescript"
        onMount={(editor) => editorRef(editor)}
      />
    </div>
  );
}

Create Monaco before binding collaboration. Choose exactly one binding path for each manager.Automatic binding: pass editor to createCollaboration(). The manager binds it during initialization, so do not call bindEditor() afterward.

import * as monaco from 'monaco-editor';
import { createCollaboration } from '@veltdev/monaco-crdt';

async function initializeMonaco(client) {
  const host = document.getElementById('editor');
  if (!host) throw new Error('Monaco host #editor was not found');

  const editor = monaco.editor.create(
    host,
    {
      value: '',
      language: 'typescript',
      theme: 'vs-dark',
    },
  );

  const manager = await createCollaboration({
    editorId: DOCUMENT_ID,
    veltClient: client,
    editor,
    initialContent: '// Start writing here\n',
    cursorData: { name: 'Ada', color: '#2563eb' },
    onError: (error) => console.error('Collaboration error:', error),
  });

  return { editor, manager };
}

Attach later: create Monaco, omit editor when creating the manager, then call bindEditor(editor) once. This is useful when your application deliberately separates manager creation from editor registration or later replaces the bound editor.

const host = document.getElementById('editor');
if (!host) throw new Error('Monaco host #editor was not found');

const editor = monaco.editor.create(
  host,
  { value: '', language: 'typescript' },
);

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  veltClient: client,
  initialContent: '// Start writing here\n',
});

await manager.bindEditor(editor);

For shared models or custom editor surfaces, bindEditor() also accepts the model, a set of editors, a custom awareness instance, and replacement behavior:

await manager.bindEditor(editor, {
  model: editor.getModel(),
  editors: new Set([editor, diffEditor]),
  awareness: manager.getAwareness(),
  destroyExisting: true,
});

Keep the defaults unless multiple Monaco surfaces intentionally share one model. Set destroyExisting: false only when retaining the existing binding is deliberate.The complete example uses automatic binding only.

Do not provide React wrapper value or defaultValue, or use Monaco’s local value as a second content source. A directly constructed editor can start with value: ''; use initialContent on the collaboration manager to seed shared text.

Step 4: Status Monitoring (Optional)

Use the hook’s reactive state, component callbacks, or manager subscriptions:

React / Next.js
Other Frameworks

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

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

  return () => {
    offStatus();
    offSynced();
  };
}, [manager]);

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

// Cleanup:
offStatus();
offSynced();

Local Monaco edits continue while disconnected and synchronize when the provider reconnects.

Step 5: Version Management (Optional)

React / Next.js
Other Frameworks

const {
  versions,
  saveVersion,
  restoreVersion,
  refreshVersions,
} = useCollaboration({ editorId: DOCUMENT_ID });

const versionId = await saveVersion('Working parser');
await refreshVersions();
await restoreVersion(versionId);
await refreshVersions();

const versionId = await manager.saveVersion('Working parser');
let versions = await manager.getVersions();

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

Restoring a version changes the shared Y.Text for all collaborators. Refresh the version list after each save or restore. For multi-tab interfaces, also refresh on window focus or visibility changes. If peers need immediate metadata updates, broadcast a small awareness event and refresh when they receive it.

Step 6: Force Reset Initial Content (Optional)

initialContent is inserted only when the shared text is new and empty:

React / Next.js
Other Frameworks

<MonacoCrdtEditor
  editorId={DOCUMENT_ID}
  initialContent={'function main() {\n  return true;\n}\n'}
/>

For an explicit reset workflow:

<MonacoCrdtEditor
  editorId={DOCUMENT_ID}
  initialContent=""
  forceResetInitialContent
/>

Set the reset flag when creating a new manager for an explicit reset workflow:

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  veltClient: client,
  editor,
  initialContent: '',
  forceResetInitialContent: true,
});

forceResetInitialContent clears the existing shared text. Do not enable it during normal page loads.

Step 7: Style Remote Cursors

y-monaco adds remote selection decorations to Monaco. Add base styles:

.yRemoteSelection {
  background-color: rgba(37, 99, 235, 0.2);
  opacity: 1;
}

.yRemoteSelectionHead {
  border-left: 2px solid #2563eb;
  min-height: 1.2em;
}

These fallback styles keep remote selections and carets visible. To apply each collaborator’s awareness color and add name labels, create client-specific rules from awareness state:

React / Next.js
Other Frameworks

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

  const awareness = manager.getAwareness();
  const doc = manager.getDoc();
  if (!awareness || !doc) return;

  const style = document.createElement('style');
  document.head.appendChild(style);

  const render = () => {
    const rules: string[] = [];
    awareness.getStates().forEach((state: any, clientId: number) => {
      if (clientId === doc.clientID || !state?.user) return;

      const color = state.user.color || '#2563eb';
      const colorLight = state.user.colorLight || `${color}33`;
      const name = String(state.user.name || 'Collaborator').replace(/"/g, '\\"');

      rules.push(`
        .yRemoteSelection-${clientId} { background-color: ${colorLight}; }
        .yRemoteSelectionHead-${clientId} { border-left: 2px solid ${color}; position: relative; }
        .yRemoteSelectionHead-${clientId}::after {
          content: "${name}";
          position: absolute;
          top: -1.55rem;
          left: -1px;
          background: ${color};
          color: white;
          padding: 2px 7px;
          border-radius: 4px;
          white-space: nowrap;
        }
      `);
    });
    style.textContent = rules.join('\n');
  };

  awareness.on('change', render);
  render();

  return () => {
    awareness.off('change', render);
    style.remove();
  };
}, [manager]);

function installCursorStyles(manager) {
  const awareness = manager.getAwareness();
  const doc = manager.getDoc();
  if (!awareness || !doc) return () => {};

  const style = document.createElement('style');
  document.head.appendChild(style);

  const render = () => {
    const rules = [];
    awareness.getStates().forEach((state, clientId) => {
      if (clientId === doc.clientID || !state?.user) return;

      const color = state.user.color || '#2563eb';
      const colorLight = state.user.colorLight || `${color}33`;
      const name = String(state.user.name || 'Collaborator').replace(/"/g, '\\"');

      rules.push(`
        .yRemoteSelection-${clientId} { background-color: ${colorLight}; }
        .yRemoteSelectionHead-${clientId} {
          border-left: 2px solid ${color};
          position: relative;
        }
        .yRemoteSelectionHead-${clientId}::after {
          content: "${name}";
          position: absolute;
          top: -1.55rem;
          left: -1px;
          background: ${color};
          color: white;
          padding: 2px 7px;
          border-radius: 4px;
          white-space: nowrap;
        }
      `);
    });
    style.textContent = rules.join('\n');
  };

  awareness.on('change', render);
  render();

  return () => {
    awareness.off('change', render);
    style.remove();
  };
}

const removeCursorStyles = installCursorStyles(manager);

Call removeCursorStyles() before destroying the manager.

Pass local identity with cursorData; when omitted, the adapter falls back to the authenticated Velt user.

Step 8: 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);
  });

// Cleanup:
crdtSubscription.unsubscribe();

Step 9: 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 10: Error Handling (Optional)

React / Next.js
Other Frameworks

const collab = useCollaboration({
  editorId: DOCUMENT_ID,
  onError: (error) => console.error('Collaboration error:', error),
});

if (collab.error) return <div>Error: {collab.error.message}</div>;

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  veltClient: client,
  editor,
  onError: (error) => {
    console.error('Monaco collaboration error:', error);
  },
});

if (!manager.getYText() || !manager.getBinding()) {
  manager.destroy();
  editor.dispose();
  throw new Error('Monaco collaboration did not initialize');
}

Manager methods return safe fallback values when collaboration resources are unavailable.

Step 11: Access Collaboration Primitives (Advanced)

React / Next.js
Other Frameworks

The hook exposes commonly used primitives:

const { primitives } = useCollaboration({ editorId: DOCUMENT_ID });

const ytext = primitives?.ytext;
const awareness = primitives?.awareness;
const undoManager = primitives?.undoManager;
const doc = primitives?.doc;
const provider = primitives?.provider;

The manager exposes the same resources plus the binding, editor, and store:

const primitives = manager.getCollaborationPrimitives();
const ytext = manager.getYText();
const doc = manager.getDoc();
const provider = manager.getProvider();
const awareness = manager.getAwareness();
const undoManager = manager.getUndoManager();
const binding = manager.getBinding();
const editor = manager.getEditor();
const store = manager.getStore();

Use manager.getUndoManager()?.undo() and redo() for collaboration-aware history. Do not add a separate Monaco history owner for the shared model.

Step 12: Enable, Disable, and Cleanup

React / Next.js
Other Frameworks

Delay or disable manager creation while continuing to render Monaco:

<MonacoCrdtEditor
  editorId={DOCUMENT_ID}
  enabled={Boolean(user && documentReady)}
/>

The component and hook destroy the collaboration manager automatically. The hook also returns destroy() for early teardown. If you created Monaco yourself, dispose the editor and model separately because the manager does not own them.

Keep the disposer returned by every subscription. Destroy collaboration before disposing the Monaco editor:

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

manager.destroy();
editor.dispose();

The manager destroys its MonacoBinding, provider, awareness listeners, and undo manager. It does not own the editor created by your application.

Step 13: Client-only Rendering

Monaco depends on browser APIs. In Next.js, load the collaborative editor without server-side rendering: Configure Monaco workers in the application bundler as well. For example, a Vite application can install the core editor worker before Monaco is created:

import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';

self.MonacoEnvironment = {
  getWorker() {
    return new editorWorker();
  },
};

Add language-specific workers the same way when the configured Monaco languages require them.

React / Next.js
Other Frameworks

import dynamic from 'next/dynamic';

const CollaborativeMonaco = dynamic(
  () => import('./CollaborativeMonaco'),
  { ssr: false },
);

Notes

Uncontrolled model: Do not control the wrapper with value or defaultValue. A direct Monaco instance may start empty, but the bound Y.Text owns shared content.
One dependency instance: Deduplicate yjs, y-protocols, and monaco-editor to avoid incompatible constructors and awareness instances.
Unique editorId: Collaborators must use the same Velt document context and editorId.
Plain-text model: Monaco content is stored in Y.Text; the Monaco language affects editing behavior, not shared data format.
Store identity: The manager creates a text Store with content key content and source metadata monaco.
Remote cursors: y-monaco supplies decorations; your CSS controls labels and colors.
One binding path: Passing editor to createCollaboration() auto-binds it. If you omit editor, call bindEditor(editor) later. Never do both for the same manager.
Multiple editors: Give independent models different editorId values. Editors sharing one model can be passed through bindEditor() options.
Other Frameworks lifecycle: Unsubscribe events and cursor-style listeners, destroy the manager, and then dispose the Monaco editor.
Client-only: Render Monaco only in the browser.
Production authentication: Use Velt’s recommended server-backed authentication flow.

Testing and Debugging

To test collaboration:

Log in as two unique users in separate browser profiles.
Open the same Velt document and Monaco editorId.
Type, select text, undo, and redo in both windows.
Save and restore a version, then reload and verify persistence.

Common issues:

Yjs was already imported: Deduplicate yjs and remove nested or linked duplicate copies.
Text does not sync: Remove value and defaultValue, and confirm both clients use the same document and editorId.
Editor never initializes: Confirm Monaco is mounted, Velt is ready, and a user is identified.
Cursor labels are missing: Add the dynamic client-ID styles or supply your own awareness renderer.
SSR errors: Load the Monaco component client-side only.

Use the VeltCrdtStoreMap debugging interface to inspect the shared text and provider state.

Complete Example

React / Next.js
Other Frameworks

Complete App.tsx

import { useEffect, useState } from 'react';
import { MonacoCrdtEditor } from '@veltdev/monaco-crdt-react';
import {
  VeltProvider,
  useCurrentUser,
  useSetDocuments,
} from '@veltdev/react';
import type { CollaborationManager, SyncStatus } from '@veltdev/monaco-crdt-react';
import './monaco-cursors.css';

const DOCUMENT_ID = 'monaco-crdt-demo-doc-1';

const USER = {
  userId: 'ada',
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  organizationId: 'my-org-id',
  color: '#2563eb',
};

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 CollaborativeEditor() {
  const user = useCurrentUser();
  const { setDocuments } = useSetDocuments();
  const [status, setStatus] = useState<SyncStatus>('connecting');
  const [manager, setManager] = useState<CollaborationManager | null>(null);
  const [versionName, setVersionName] = useState('');
  const [documentReady, setDocumentReady] = useState(false);

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

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

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

  return (
    <main>
      <p>Status: {status} | Synced: {manager?.synced ? 'Yes' : 'No'}</p>
      <input
        value={versionName}
        onChange={(event) => setVersionName(event.target.value)}
        placeholder="Version name"
      />
      <button onClick={saveVersion}>Save version</button>
      <MonacoCrdtEditor
        editorId={DOCUMENT_ID}
        language="typescript"
        theme="vs-dark"
        height="500px"
        initialContent={'export function hello() {\n  return "world";\n}\n'}
        cursorData={{ name: user.name, color: '#2563eb' }}
        options={{ minimap: { enabled: false }, wordWrap: 'on' }}
        onStatusChange={setStatus}
        onManagerReady={setManager}
        onError={console.error}
      />
    </main>
  );
}

export default function App() {
  return (
    <VeltProvider
      apiKey="YOUR_VELT_API_KEY"
      authProvider={authProvider}
    >
      <CollaborativeEditor />
    </VeltProvider>
  );
}

Complete monaco-cursors.css

.yRemoteSelection {
  background-color: rgba(37, 99, 235, 0.2);
  opacity: 1;
}

.yRemoteSelectionHead {
  border-left: 2px solid #2563eb;
  min-height: 1.2em;
}

This complete example uses automatic binding: it creates Monaco first and passes that editor to createCollaboration(). It never calls bindEditor().

Complete app.ts

import * as monaco from 'monaco-editor';
import { initVelt } from '@veltdev/client';
import {
  createCollaboration,
  type CollaborationManager,
} from '@veltdev/monaco-crdt';
import './monaco-cursors.css';

const DOCUMENT_ID = 'monaco-crdt-demo-doc-1';

let resources: {
  editor: monaco.editor.IStandaloneCodeEditor;
  manager: CollaborationManager;
  offStatus: () => void;
  offSynced: () => void;
  crdtSubscription: { unsubscribe: () => void };
  removeCursorStyles: () => void;
} | null = null;

function installCursorStyles(manager: CollaborationManager) {
  const awareness = manager.getAwareness();
  const doc = manager.getDoc();
  if (!awareness || !doc) return () => {};

  const style = document.createElement('style');
  document.head.appendChild(style);

  const render = () => {
    const rules: string[] = [];
    awareness.getStates().forEach((state: any, clientId: number) => {
      if (clientId === doc.clientID || !state?.user) return;
      const color = state.user.color || '#2563eb';
      const colorLight = state.user.colorLight || `${color}33`;
      const name = String(state.user.name || 'Collaborator').replace(/"/g, '\\"');

      rules.push(`
        .yRemoteSelection-${clientId} { background-color: ${colorLight}; }
        .yRemoteSelectionHead-${clientId} {
          border-left: 2px solid ${color};
          position: relative;
        }
        .yRemoteSelectionHead-${clientId}::after {
          content: "${name}";
          position: absolute;
          top: -1.55rem;
          left: -1px;
          background: ${color};
          color: white;
          padding: 2px 7px;
          border-radius: 4px;
          white-space: nowrap;
        }
      `);
    });
    style.textContent = rules.join('\n');
  };

  awareness.on('change', render);
  render();

  return () => {
    awareness.off('change', render);
    style.remove();
  };
}

async function initializeMonaco(client) {
  const editor = monaco.editor.create(
    document.getElementById('editor')!,
    {
      value: '',
      language: 'typescript',
      theme: 'vs-dark',
      minimap: { enabled: false },
      automaticLayout: true,
    },
  );

  const manager = await createCollaboration({
    editorId: DOCUMENT_ID,
    veltClient: client,
    editor,
    initialContent: 'export function hello() {\n  return "world";\n}\n',
    cursorData: {
      name: 'Ada Lovelace',
      color: '#2563eb',
      colorLight: '#2563eb33',
    },
    onError: (error) => console.error('Collaboration error:', error),
  });

  if (!manager.getYText() || !manager.getBinding()) {
    manager.destroy();
    editor.dispose();
    throw new Error('Monaco collaboration did not initialize');
  }

  const offStatus = manager.onStatusChange((status) => {
    document.getElementById('status')!.textContent = status;
  });
  const offSynced = manager.onSynced((synced) => {
    document.getElementById('synced')!.textContent = synced ? 'Yes' : 'No';
  });
  const crdtSubscription = client
    .getCrdtElement()
    .on('updateData')
    .subscribe((event) => {
      if (event) console.log('CRDT update:', event);
    });
  const removeCursorStyles = installCursorStyles(manager);

  document.getElementById('undo')?.addEventListener('click', () => {
    manager.getUndoManager()?.undo();
  });
  document.getElementById('redo')?.addEventListener('click', () => {
    manager.getUndoManager()?.redo();
  });
  document.getElementById('save-version')?.addEventListener('click', async () => {
    const versionId = await manager.saveVersion('Before refactor');
    console.log('Saved version:', versionId, await manager.getVersions());
  });

  resources = {
    editor,
    manager,
    offStatus,
    offSynced,
    crdtSubscription,
    removeCursorStyles,
  };
}

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: 'Monaco CRDT Demo',
});

let initializationStarted = false;
const initSubscription = client.getVeltInitState().subscribe((isReady) => {
  if (!isReady || initializationStarted) return;
  initializationStarted = true;
  void initializeMonaco(client);
});

window.addEventListener('beforeunload', () => {
  resources?.removeCursorStyles();
  resources?.crdtSubscription.unsubscribe();
  resources?.offStatus();
  resources?.offSynced();
  initSubscription.unsubscribe();

  resources?.manager.destroy();
  resources?.editor.dispose();
});

How It Works

React applications initialize Velt with VeltProvider; other frameworks initialize one client with initVelt(). Both authenticate before setting the shared document.
React wrappers wait for Velt, an authenticated user, and a mounted Monaco editor. Other frameworks wait for client readiness and create Monaco before collaboration.
The manager creates a Velt CRDT store and obtains the shared Y.Text.
Passing editor to the factory auto-binds y-monaco; alternatively, a manager created without an editor can be bound once later with bindEditor().
y-monaco maps awareness selections to editor decorations. Static CSS supplies a visible fallback caret, while dynamic rules apply each collaborator’s color and label.
Local text transactions merge with concurrent remote transactions, and Velt persists the Yjs update stream and named versions.

APIs

React: MonacoCrdtEditor

Prop	Type	Required	Description
`editorId`	`string`	No*	Unique key for the shared editor.
`documentId`	`string`	No*	Used as `editorId` when `editorId` is omitted.
`veltClient`	`Velt`	No	Overrides the context client.
`initialContent`	`string`	No	Initial plain text for a new document.
`forceResetInitialContent`	`boolean`	No	Replaces existing shared text.
`cursorData`	`MonacoCursorData`	No	Local cursor identity and colors.
`debounceMs`	`number`	No	Backend store debounce interval.
`enabled`	`boolean`	No	Creates or destroys collaboration while mounted.
`onError`	`(error: Error) => void`	No	Receives non-fatal errors.
`onStatusChange`	`(status: SyncStatus) => void`	No	Receives status changes.
`onManagerReady`	`(manager) => void`	No	Receives the initialized manager.
`onEditorReady`	`(editor) => void`	No	Receives the Monaco editor.
`onMount`	`OnMount`	No	Receives the normal Monaco mount callback after capture.

*Provide either editorId or documentId. Other Monaco React props are passed through except value and defaultValue.

React: useCollaboration()

Return	Type	Description
`editorRef`	`(editor \| null) => void`	Receives a Monaco editor instance.
`primitives`	`CollaborationPrimitives \| null`	Shared Yjs and provider objects.
`manager`	`CollaborationManager \| null`	Base manager.
`isLoading`	`boolean`	Initialization state.
`synced` / `isSynced`	`boolean`	Initial backend sync state.
`status`	`SyncStatus`	Connection status.
`error`	`Error \| null`	Latest error.
`versions`	`Version[]`	Saved versions.
`saveVersion(name)`	`Promise<string>`	Saves a version.
`restoreVersion(id)`	`Promise<boolean>`	Restores a version.
`refreshVersions()`	`Promise<Version[]>`	Reloads versions.
`destroy()`	`void`	Destroys collaboration early.

Other Frameworks: createCollaboration()

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

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  veltClient: client,
  editor,
  initialContent: '// Shared text\n',
  cursorData: { name: 'Ada', color: '#2563eb' },
  debounceMs: 250,
  onError: console.error,
});

This factory example uses automatic binding. For attach-later binding, omit editor and follow the separate alternative in Step 3; never combine the two paths.

Config	Type	Required	Description
`editorId`	`string`	Yes	Stable key for the shared Monaco model.
`veltClient`	`Velt`	Yes	Initialized, authenticated Velt client.
`editor`	`IStandaloneCodeEditor`	No	Monaco instance to bind automatically during initialization.
`initialContent`	`string`	No	Plain text inserted only for a new, empty shared value.
`forceResetInitialContent`	`boolean`	No	Explicitly replaces existing shared text.
`cursorData`	`MonacoCursorData`	No	Awareness identity and cursor colors.
`debounceMs`	`number`	No	Backend persistence debounce interval.
`onError`	`(error: Error) => void`	No	Receives non-fatal initialization and runtime errors.

CollaborationManager Methods

Method or property	Description
`initialize()`	Initializes the shared store.
`destroy()`	Destroys binding and collaboration resources.
`bindEditor(editor, options?)`	Binds or rebinds a Monaco model.
`getCollaborationPrimitives()`	Returns shared primitives.
`initialized`, `synced`, `status`	Current manager state.
`onStatusChange(callback)`	Subscribes to connection status.
`onSynced(callback)`	Subscribes to sync state.
`getDoc()`	Returns the `Y.Doc`.
`getText()` / `getYText()`	Returns the shared `Y.Text`.
`getProvider()`	Returns the Velt sync provider.
`getAwareness()`	Returns Yjs awareness.
`getUndoManager()`	Returns the shared undo manager.
`getBinding()`	Returns the `MonacoBinding`.
`getEditor()`	Returns the bound Monaco editor.
`getStore()`	Returns the Velt CRDT store.
`saveVersion(name)`	Saves a version.
`getVersions()`	Lists versions.
`restoreVersion(id)`	Restores a version.
`setStateFromVersion(version)`	Applies a supplied version object.

Exported Types

CollaborationConfig, CollaborationPrimitives, BindEditorOptions
UseCollaborationConfig / UseMonacoCrdtConfig
UseCollaborationReturn / MonacoCrdtHookResult
MonacoCrdtEditorProps, MonacoCursorData, MonacoBindingInstance
SyncStatus, Unsubscribe, Version

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Monaco Editor

Prerequisites

Setup

Step 1: Install Dependencies

Step 2: Setup Velt

Step 3: Initialize Collaborative Editor

Step 4: Status Monitoring (Optional)

Step 5: Version Management (Optional)

Step 6: Force Reset Initial Content (Optional)

Step 7: Style Remote Cursors

Step 8: CRDT Event Subscription (Optional)

Step 9: Custom Encryption (Optional)

Step 10: Error Handling (Optional)

Step 11: Access Collaboration Primitives (Advanced)

Step 12: Enable, Disable, and Cleanup

Step 13: Client-only Rendering

Notes

Testing and Debugging

Complete Example

How It Works

APIs

React: MonacoCrdtEditor

React: useCollaboration()

Other Frameworks: createCollaboration()

CollaborationManager Methods

Exported Types

​Prerequisites

​Setup

​Step 1: Install Dependencies

​Step 2: Setup Velt

​Step 3: Initialize Collaborative Editor

​Step 4: Status Monitoring (Optional)

​Step 5: Version Management (Optional)

​Step 6: Force Reset Initial Content (Optional)

​Step 7: Style Remote Cursors

​Step 8: CRDT Event Subscription (Optional)

​Step 9: Custom Encryption (Optional)

​Step 10: Error Handling (Optional)

​Step 11: Access Collaboration Primitives (Advanced)

​Step 12: Enable, Disable, and Cleanup

​Step 13: Client-only Rendering

​Notes

​Testing and Debugging

​Complete Example

​How It Works

​APIs

​React: MonacoCrdtEditor

​React: useCollaboration()

​Other Frameworks: createCollaboration()

​CollaborationManager Methods

​Exported Types

Prerequisites

Setup

Step 1: Install Dependencies

Step 2: Setup Velt

Step 3: Initialize Collaborative Editor

Step 4: Status Monitoring (Optional)

Step 5: Version Management (Optional)

Step 6: Force Reset Initial Content (Optional)

Step 7: Style Remote Cursors

Step 8: CRDT Event Subscription (Optional)

Step 9: Custom Encryption (Optional)

Step 10: Error Handling (Optional)

Step 11: Access Collaboration Primitives (Advanced)

Step 12: Enable, Disable, and Cleanup

Step 13: Client-only Rendering

Notes

Testing and Debugging

Complete Example

How It Works

APIs

React: MonacoCrdtEditor

React: useCollaboration()

Other Frameworks: createCollaboration()

CollaborationManager Methods

Exported Types