CodeMirror Editor

Documentation Index

Fetch the complete documentation index at: https://docs.velt.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Prerequisites

• Node.js (v14 or higher)
• React (v16.8 or higher for hooks)
• A Velt account with an API key (sign up)
• Optional: TypeScript for type safety

​

Setup

​

Step 1: Install Dependencies

npm install @veltdev/codemirror-crdt-react @veltdev/react

npm install @veltdev/codemirror-crdt @veltdev/client y-codemirror.next

​

Step 2: Setup Velt

​

Step 3: Initialize Velt CRDT Extension

• Initialize the Velt CRDT extension and use it to initialize the CodeMirror editor.
• Pass an editorId to uniquely identify each editor instance you have in your app. This is especially important when you have multiple editors in your app.

// Initialize the Velt CRDT extension
const { store, isLoading } = useVeltCodeMirrorCrdtExtension({ editorId });

useEffect(() => {
  if (!store || !editorRef.current) return;

  const startState = EditorState.create({
    doc: store.getYText()?.toString() ?? '',
    extensions: [
      basicSetup,
      yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() }),
    ],
  });

  viewRef.current = new EditorView({
      state: startState,
      parent: editorRef.current,
  });

  return () => viewRef.current?.destroy();
}, [store]);

// Create the CRDT store
const store = await createVeltCodeMirrorStore({
  editorId: editorId,
  veltClient: veltClient,
});

// Create editor state with yCollab extension
const startState = EditorState.create({
  doc: store.getYText()?.toString() ?? '',
  extensions: [
    basicSetup,
    yCollab(store.getYText(), store.getAwareness(), {
      undoManager: store.getUndoManager(),
    }),
  ],
});

// Create editor view
const view = new EditorView({
  state: startState,
  parent: editorContainer,
});

​

Notes

• Unique editorId: Use a unique editorId per editor instance.
• Wait for auth: Initialize the store only after the Velt client is ready.
• Use yCollab: Pass the store’s Yjs text, awareness, and undo manager to yCollab.
• Initialize and clean up: Destroy the EditorView and store on unmount to avoid leaks.

​

Testing and Debugging

1. Login two unique users on two browser profiles and open the same page in both.
2. Edit in one window and verify changes and cursors appear in the other.

• Cursors not appearing: Ensure each editor has a unique editorId and users are authenticated. Also ensure that you are logged in with two different users in two different browser profiles.
• Editor not loading: Confirm the Velt client is initialized and the API key is valid.
• Disconnected session: Check network.

​

Complete Example

// Import required modules
import { useVeltCodeMirrorCrdtExtension } from "@veltdev/codemirror-crdt-react";
import { yCollab } from "y-codemirror.next";
import { EditorState } from "@codemirror/state";
import { basicSetup, EditorView } from "codemirror";

// Add hook in your codemirror editor component
const { store, isLoading } = useVeltCodeMirrorCrdtExtension({ editorId });

useEffect(() => {
    if (!store || !editorRef.current) return;

    // Clean up existing view if any
    viewRef.current?.destroy();

    const startState = EditorState.create({
        doc: store.getYText()?.toString() ?? '',
        extensions: [
            basicSetup,
            autocompletion(),
            yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() }),
        ],
    });

    viewRef.current = new EditorView({
        state: startState,
        parent: editorRef.current,
    });

    return () => {
        viewRef.current?.destroy();
        viewRef.current = null;
    };
}, [store]);

// Import required modules
import { initVelt } from '@veltdev/client';
import { createVeltCodeMirrorStore } from '@veltdev/codemirror-crdt';
import { yCollab } from 'y-codemirror.next';
import { EditorState } from '@codemirror/state';
import { basicSetup, EditorView } from 'codemirror';

// Step 1: Initialize Velt client
const veltClient = await initVelt('YOUR_API_KEY');

// Step 2: Authenticate user
await veltClient.identify({ userId: 'user-1', name: 'John Doe' });

// Step 3: Set document
await veltClient.setDocument('my-document-id');

// Step 4: Create CRDT store
const store = await createVeltCodeMirrorStore({
  editorId: 'velt-codemirror-crdt-demo',
  veltClient: veltClient,
});

// Step 5: Create CodeMirror editor
const startState = EditorState.create({
  doc: store.getYText()?.toString() ?? '',
  extensions: [
    basicSetup,
    yCollab(store.getYText(), store.getAwareness(), {
      undoManager: store.getUndoManager(),
    }),
  ],
});

const view = new EditorView({
  state: startState,
  parent: document.getElementById('editor'),
});

// Cleanup on unmount
view.destroy();
store.destroy();

​

APIs

​

Custom Encryption

async function encryptData(config: EncryptConfig<number[]>): Promise<string> {
  const encryptedData = await yourEncryptDataMethod(config.data);
  return encryptedData;
}

async function decryptData(config: DecryptConfig<string>): Promise<number[]> {
  const decryptedData = await yourDecryptDataMethod(config.data);
  return decryptedData;
}

const encryptionProvider: VeltEncryptionProvider<number[], string> = {
  encrypt: encryptData,
  decrypt: decryptData,
};

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

async function encryptData(config: EncryptConfig<number[]>): Promise<string> {
  const encryptedData = await yourEncryptDataMethod(config.data);
  return encryptedData;
}

async function decryptData(config: DecryptConfig<string>): Promise<number[]> {
  const decryptedData = await yourDecryptDataMethod(config.data);
  return decryptedData;
}

const encryptionProvider: VeltEncryptionProvider<number[], string> = {
  encrypt: encryptData,
  decrypt: decryptData,
};

client.setEncryptionProvider(encryptionProvider);

​

Initialization

const { store, isLoading } = useVeltCodeMirrorCrdtExtension({ 
  editorId: 'velt-codemirror-crdt-demo' 
});

import { createVeltCodeMirrorStore } from '@veltdev/codemirror-crdt';

const store = await createVeltCodeMirrorStore({
  editorId: 'velt-codemirror-crdt-demo',
  veltClient: client,
  initialContent: '// Start coding...',
});

​

Store Methods

​

store.getStore()

• Returns: Store<string>

const underlying = store.getStore();

​

store.getYDoc()

• Returns: Y.Doc

const ydoc = store.getYDoc();

​

store.getYText()

• Returns: Y.Text | null

const docText = store.getYText()?.toString() ?? '';

​

store.getAwareness()

• Returns: Awareness

yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() });

​

store.getUndoManager()

• Returns: Y.UndoManager

const extensions = [
  basicSetup,
  yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() }),
];

​

store.destroy()

• Returns: void

// Cleanup when done
store.destroy();