y-excalidraw

Excalidraw whiteboard binding for Yjs - Demo

This binding binds a Y.Array to a Excalidraw whiteboard.

npm install y-excalidraw

Features

• Sync Excalidraw whiteboard elements
• Awareness: Sync remote cursor and selections
• Assets/Files syncing
• Shared Undo / Redo (each client has its own undo-/redo-history) - as a separate plugin

Todo

• Add tests
• Check the feasibility of making every element key collaborative
• Add benchmarks

Note

The sync is at the excalidraw array item (element) level but not at the element key level. Even the excalidraw cloud offering doesn't support that (Link). It would not be very hard to add it here but there are 2 issues that might crop up

• If operation 1 on client 1 changes 2 keys (keyA: ValueA, keyB: ValueB) on an array element. Then say operation 2 on client 2 changes 1 key (keyA: ValueZ) on the same array element. If the sync was at the key level then the final array item will be - (keyA: ValueZ, keyB: ValueB) and I am not sure if this final state is always valid. Are all keys of an excalidraw array element independent of each other?
• Since on any change on the canvas, excalidraw onChange callback fires with the complete new state of the canvas but no diffs. So to make the app reactive at key level we would need to do a deep diff to figure out what key excatly changed. I am not sure how much extra runtime overhead this will introduce, will need to benchmark

Helpful resources

• Excalidraw team's blog on how they achieved p2p sharing with excalidraw -> Link
• How to move items in an array in a safe manner, yjs discussion -> Link
• Another intgeration of yjs with excalidraw. Most of the setup code is inspired from there -> Link
• Code for the demo was taken from yjs-codemirror.next repo -> Link

Getting Started

Install y-excalidraw (Make sure excalidraw and yjs are already installed)

npm install y-excalidraw

Example

import * as React from "react";

import { Excalidraw } from "@excalidraw/excalidraw";
import * as Y from "yjs";

import type { ExcalidrawImperativeAPI } from "@excalidraw/excalidraw/types/types";
import { ExcalidrawBinding } from "y-excalidraw"

import { WebrtcProvider } from 'y-webrtc'

import * as random from 'lib0/random'

export const usercolors = [
  { color: '#30bced', light: '#30bced33' },
  { color: '#6eeb83', light: '#6eeb8333' },
  { color: '#ffbc42', light: '#ffbc4233' },
  { color: '#ecd444', light: '#ecd44433' },
  { color: '#ee6352', light: '#ee635233' },
  { color: '#9ac2c9', light: '#9ac2c933' },
  { color: '#8acb88', light: '#8acb8833' },
  { color: '#1be7ff', light: '#1be7ff33' }
]

export const userColor = usercolors[random.uint32() % usercolors.length]

const ydoc = new Y.Doc()
const yElements = ydoc.getArray<Y.Map<any>>('elements');  // structure = {el: NonDeletedExcalidrawElement, pos: string}
const yAssets = ydoc.getMap('assets'); // if you want manual control assets, make it as null

const provider = new WebrtcProvider('y-excalidraw-demo-room', ydoc)

provider.awareness.setLocalStateField('user', {
  name: 'Anonymous ' + Math.floor(Math.random() * 100),
  color: userColor.color,
  colorLight: userColor.light
})

export default function App() {
  const [api, setApi] = React.useState<ExcalidrawImperativeAPI | null>(null);
  const [binding, setBindings] = React.useState<ExcalidrawBinding | null>(null);
  const excalidrawRef = React.useRef(null);

  React.useEffect(() => {
    if (!api) return;

    const binding = new ExcalidrawBinding(
      yElements,
      yAssets,
      api,
      provider.awareness,
      // excalidraw dom is needed to override the undo/redo buttons in the UI as there is no way to override it via props in excalidraw
      // You might need to pass {trackedOrigins: new Set()} to undomanager depending on whether your provider sets an origin or not
      {excalidrawDom: excalidrawRef.current, undoManager: new Y.UndoManager(yElements)},
   );
    setBindings(binding);
    return () => {
      setBindings(null);
      binding.destroy();
    };
  }, [api]);

  const initData = {
    elements: yjsToExcalidraw(yElements)
  }

  return (
    <div style={{width: "100vw", height: "100vh"}} ref={excalidrawRef}>
      <Excalidraw
        initialData={initData}  // Need to set the initial data
        excalidrawAPI={setApi}
        onPointerUpdate={binding?.onPointerUpdate}
        theme="light"
      />
    </div>
  );
}

If you want to get the excalidraw array, you can use the utility function

import { yjsToExcalidraw } from "y-excalidraw"

console.log("Excalidraw json", yjsToExcalidraw(yElements))

Manual manage assets

If you want to manually manage assets, you can pass null as the second argument to the constructor.

const binding = new ExcalidrawBinding(
  yElements,
  null,
  api,
  provider.awareness,
  {excalidrawDom: excalidrawRef.current, undoManager: new Y.UndoManager(yElements)},
);

// You can now manually manage assets like s3 by generateIdForFile and addFiles

const assetsManager = {
  processedFileIds: new Set<string>(),
  processingFileIds: new Set<string>(),
  generateIdForFile: async (file: File) => {
    const key = file.name; // generate a unique key for the file

    const command = new PutObjectCommand({
      Bucket: bucketName,
      Key: key,
      Body: file,
    });
    await s3Client.send(command);

    return key;
  },
  addFiles: (elements: NonDeletedExcalidrawElement[]) => {
    const newFileIds = new Set<string>();
    for (const element of elements) {
      if (element.fileId && !this.processedFileIds.has(element.fileId) && !this.processingFileIds.has(element.fileId)) {
        newFileIds.add(element.fileId);
      }
    }
    this.processingFileIds = new Set([...this.processingFileIds, ...newFileIds]);
    try {
      const files = await Promise.all(newFileIds.map(async (fileId) => {
        const command = new GetObjectCommand({
          Bucket: bucketName,
          Key: fileId, // fileId is the key generated by generateIdForFile
        });
        const response = await s3Client.send(command);
        const str = await response.Body.transformToString();
        return {
          mimeType: "image/png", // TODO: get the actual mime type
          id: fileId,
          dataURL: str,
          created: Date.now(),
        };
      }));
    this.processedFileIds = new Set([...this.processedFileIds, ...newFileIds]);
    this.processingFileIds = new Set([...this.processingFileIds].filter((id) => !newFileIds.has(id)));
    api.addFiles(files);
    } catch (e) {
      console.error(e);
      // error catch and remove from processingFileIds
      this.processingFileIds = new Set([...this.processingFileIds].filter((id) => !newFileIds.has(id)));
    }
  }
}

// bind to excalidraw onChange
api.onChange(function(elements) {
  assetsManager.call(assetsManager, assetsManager.addFiles(elements))
})

  return (
    <div style={{width: "100vw", height: "100vh"}} ref={excalidrawRef}>
      <Excalidraw
        // {...prevProps}
        ongenerateIdForFile={assetsManager.generateIdForFile}
      />
    </div>
  );