The editor is a React component you install; persistence and collaboration are yours to build.

Excalidraw technical tour

What it is

Excalidraw is an open-source whiteboard editor that ships both as a hosted app and as a React component

License

MIT

Developed in the open in the excalidraw/excalidraw repository.

Package

@excalidraw/ excalidraw

A React component you mount in your own page. This is what an embedder ships.

Hosted app

excalidraw.com

The same editor plus share links and live rooms. Excalidraw+ is the paid product from the same team.

Drawing model

Canvas + JSON

Scenes are drawn on HTML canvas, with Rough.js for the sketched look, and saved as JSON in .excalidraw files.

Basis for this deck: no source documents or repository snapshot came with this brief. What follows is recalled knowledge of the public project, not checked against any commit, and paths may have moved. File, line and star counts are left out rather than guessed.

How the code is organised

The code splits into one app, one embeddable package and a few supporting packages

excalidraw-app/

The excalidraw.com site: collaboration, Firebase access, share links. An application, not the published package.

depends on

packages/excalidraw/

The npm package an embedder installs: components/, actions/, renderer/, scene/, data/.

depends on

packages/element/

Element types, bounds, binding

packages/math/

Geometry primitives

packages/common/

Shared constants and helpers

packages/utils/

Standalone utilities

Also relevant to an embedder

examples/

Integration samples, including with-nextjs and with-script-in-browser.

dev-docs/

Source of the developer documentation, including the package API.

excalidraw-room

A separate repository, not in this tree: the socket relay behind live rooms.

Capabilities a team would use

Teams get four usable groups: drawing, data in and out, scripted scenes and UI control

Drawing

  • Rectangle, diamond, ellipse, arrow, line, freehand, text, image
  • Arrows that bind to shapes and follow them
  • Frames for grouping areas of a scene
  • Reusable shape libraries

Data in and out

  • initialData to load a scene
  • onChange to receive every change
  • exportToBlob, exportToSvg, exportToCanvas for images
  • serializeAsJSON for the scene file

Scripted scenes

  • excalidrawAPI prop returns an imperative handle
  • updateScene, getSceneElements on that handle
  • convertToExcalidrawElements builds scenes from short skeletons
  • @excalidraw/ mermaid-to-excalidraw converts Mermaid

UI control

  • viewModeEnabled, zenModeEnabled, gridModeEnabled
  • theme and langCode
  • UIOptions and renderTopRightUI
  • MainMenu, WelcomeScreen, Sidebar, Footer as child components

What embedding involves

Embedding is one component and one stylesheet; the work sits in container, assets and storage

import { Excalidraw } from "@excalidraw/excalidraw";
import "@excalidraw/excalidraw/index.css";

export function Board({ scene, save }) {
  return (
    <div style={{ height: "100%" }}>
      <Excalidraw
        initialData={scene}
        onChange={save}
      />
    </div>
  );
}
  • Container. The editor fills its parent, so a parent without height renders nothing.
  • Server rendering. It is browser-only. In Next.js, load it through a dynamic import with ssr: false; see examples/with-nextjs.
  • Assets. Fonts come from a CDN by default. window.EXCALIDRAW_ASSET_PATH points them at your own host.
  • Storage. No backend is included. onChange passes elements, app state and files; saving and throttling are yours.
  • Framework. React is required. A non-React product mounts it in a React island.

Collaboration and sharing

Live collaboration lives in the app, not the package, so an embedder supplies transport and storage

Browser A encrypts locally; key from URL fragment Relay excalidraw-room forwards ciphertext Browser B decrypts, then merges per element Firebase encrypted scene and image files Hosted app only. An embedder replaces both servers.
  • Live rooms. Built in excalidraw-app/collab/Collab.tsx and Portal.tsx on socket.io.
  • Encryption. End to end. Room links carry #room=id,key, and browsers do not send a URL fragment to servers.
  • Merging. Each element has version and versionNonce; reconcileElements picks a winner per element. This is not a CRDT.
  • Share links. #json=id,key points to an encrypted snapshot uploaded by the app.
  • In the package. Hooks only: isCollaborating, onPointerUpdate, updateScene, LiveCollaborationTrigger.

Where the code carries weight and risk

The weight sits in one central component and in element geometry; the risk sits in what you would own

Weight in the code

  • packages/excalidraw/components/App.tsx is one large class component. Input handling and editor state pass through it.
  • packages/element/ holds the geometry-heavy logic, such as binding.ts and linearElementEditor.ts.
  • packages/excalidraw/renderer/ separates a static scene canvas from an interactive one.

Risk for an embedder

  • Upgrades. Releases have been versioned 0.x, so track breaking changes in packages/excalidraw/CHANGELOG.md.
  • Collaboration. App code is not a published API. Reusing it means copying and maintaining it.
  • Deep changes. Behaviour beyond props and the API handle means forking near App.tsx.
  • Accessibility. Shapes are canvas pixels, not DOM elements.

Not measured here: line counts, bundle size, performance on large scenes. Slide 7 says how to get them.

What to check first

Check five things on a pinned release before committing the team

Check

How

What it decides

1. Bundle cost

Build examples/with-nextjs and read the chunk sizes.

Whether the editor stays behind a lazy route.

2. Real scene load

Load the largest scene your product expects; profile pan, zoom and edit.

Whether canvas performance fits your use case.

3. Collaboration

Connect two clients over your transport with updateScene and reconcileElements.

The real backend cost, and end-to-end encryption or server-readable content.

4. Code weight

Count lines in App.tsx; read recent entries in CHANGELOG.md.

The upgrade budget per release, and whether a fork is affordable.

5. Compliance

Self-host assets, scan dependency licenses, test with your accessibility requirements.

Whether procurement and customer commitments allow the embed.