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
initialDatato load a sceneonChangeto receive every changeexportToBlob,exportToSvg,exportToCanvasfor imagesserializeAsJSONfor the scene file
Scripted scenes
excalidrawAPIprop returns an imperative handleupdateScene,getSceneElementson that handleconvertToExcalidrawElementsbuilds scenes from short skeletons@excalidraw/ mermaid-to-excalidrawconverts Mermaid
UI control
viewModeEnabled,zenModeEnabled,gridModeEnabledthemeandlangCodeUIOptionsandrenderTopRightUIMainMenu,WelcomeScreen,Sidebar,Footeras 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; seeexamples/with-nextjs. - Assets. Fonts come from a CDN by default.
window.EXCALIDRAW_ASSET_PATHpoints them at your own host. - Storage. No backend is included.
onChangepasses 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
- Live rooms. Built in
excalidraw-app/collab/Collab.tsxandPortal.tsxon 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
versionandversionNonce;reconcileElementspicks a winner per element. This is not a CRDT. - Share links.
#json=id,keypoints 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.tsxis one large class component. Input handling and editor state pass through it.packages/element/holds the geometry-heavy logic, such asbinding.tsandlinearElementEditor.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.