This document provides a high-level introduction to the Excalidraw codebase, its organizational structure, and core architectural systems. It is intended to serve as an entry point for understanding how the different parts of the codebase fit together.
Scope: This page covers the overall architecture, monorepo organization, key systems, and how they interact. For detailed information about specific subsystems, see the following pages:
Excalidraw is an open-source virtual whiteboard application that enables users to create hand-drawn style diagrams and collaborate in real-time. The project consists of two main deliverables:
@excalidraw/excalidraw npm package: A React-based drawing library that can be embedded in other applications packages/excalidraw/package.json2-3 README.md54-70 packages/excalidraw/package.json41The codebase is organized as a monorepo containing the core library packages, the production application, and integration examples package.json5-9
Sources: README.md1-81 package.json1-9 packages/excalidraw/package.json1-41
The repository uses Yarn workspaces to manage multiple packages within a single monorepo package.json4-9 The workspace configuration defines three main areas:
Workspace Hierarchy
The workspace definitions are specified in the root package.json package.json5-9:
| Workspace Pattern | Purpose | Location |
|---|---|---|
excalidraw-app | Production web application (excalidraw.com) | excalidraw-app/ |
packages/* | Core reusable library packages | packages/excalidraw/ packages/element/ packages/math/ packages/common/ packages/utils/ packages/fractional-indexing/ packages/laser-pointer/ |
examples/* | Integration examples (e.g. browser script) | examples/ |
For details, see Monorepo Structure and Workspaces and Package Architecture.
Sources: package.json1-9
The Excalidraw application is built on several interconnected systems. The following diagram bridges natural language concepts to specific code entities:
System to Code Entity Mapping
| Code Entity | Responsibility |
|---|---|
App | Central orchestrator component for the editor UI and state management. |
ExcalidrawImperativeAPI | Interface for interacting with the editor instance externally packages/excalidraw/package.json5 |
Collab | Manages real-time collaboration, WebSocket communication, and Firebase integration excalidraw-app/package.json32-38 |
reconcileElements | Resolves conflicts between local and remote element states. |
StaticCanvas | Renders the main scene elements that don't change frequently. |
InteractiveCanvas | Renders active selections, multi-point editing, and temporary UI elements. |
For details, see Core Application Architecture.
The project uses Vite for development and production builds, with orchestration handled via the root package.json package.json38-64
| Script | Purpose | Implementation |
|---|---|---|
yarn start | Development server with HMR | Delegates to excalidraw-app package.json65 |
yarn build:packages | Builds packages in dependency order | common → fractional-indexing → laser-pointer → math → element → excalidraw package.json61 |
yarn build:app | Production build of web application | Vite production build in excalidraw-app package.json54 |
yarn test:all | Runs all tests and checks | Type check + unit tests + linting + formatting package.json68 |
yarn release | Publishes to npm registry | Supports @test, @next, @latest tags package.json85-88 |
The project also supports Docker-based deployment, primarily for the web application package.json53 and provides a development environment via Docker .codesandbox/Dockerfile1-5
For details, see Build System and Scripts and Deployment and Distribution.
Sources: package.json51-91 excalidraw-app/vite.config.mts11-23
| Layer | Technologies |
|---|---|
| Language | TypeScript 5.9.3 package.json37 |
| Framework | React 19.x package.json17-18 |
| Build Tool | Vite 5.x package.json38 |
| Testing | Vitest 3.x package.json43 |
| State | Jotai 2.11.0 packages/excalidraw/package.json100 |
| Package Manager | Yarn 1.22.22 (workspaces) package.json4-5 |
Sources: package.json10-48 packages/excalidraw/package.json80-117
The monorepo is split into focused packages (e.g., @excalidraw/math, @excalidraw/element) to allow independent development and modular imports. This is reflected in the workspace configuration package.json5-9 and the Vite alias configuration excalidraw-app/vite.config.mts25-92
The project utilizes ES modules for production and development, ensuring modern resolution and tree-shaking capabilities packages/excalidraw/package.json4-8
Real-time collaboration and sharing features prioritize privacy by performing end-to-end encryption entirely in the browser README.md77 Encryption logic for exporting to Excalidraw+ uses encryptData and generateEncryptionKey excalidraw-app/components/ExportToExcalidrawPlus.tsx42-43
Collaborative editing relies on reconciliation algorithms to merge remote updates while preserving local intent README.md76
Sources: README.md52-82 package.json5-9 excalidraw-app/components/ExportToExcalidrawPlus.tsx32-61