This page introduces the Excalidraw project, its purpose as a virtual whiteboard application, and the overall structure of the monorepo. It provides a high-level view of how the codebase is organized, the distinction between the npm library and the hosted application, and the foundational architecture. For detailed information about specific subsystems, refer to the child pages: Monorepo Structure and Workspaces, Package Architecture, Build System and Scripts, and Deployment and Distribution.
Excalidraw is an open-source virtual whiteboard application that enables users to create hand-drawn style diagrams, wireframes, and sketches. The project is distributed in two forms:
@excalidraw/excalidraw): A React component library that can be embedded into other applicationsThe core library provides an infinite canvas-based whiteboard with support for various drawing tools (rectangles, ellipses, arrows, lines, free-draw), image embedding, shape libraries, localization, and export to multiple formats (PNG, SVG, .excalidraw JSON).
Sources: README.md58-88
The Excalidraw codebase is organized as a Yarn workspaces monorepo, defined in package.json1-94 This structure separates concerns between reusable packages and the hosted application while enabling efficient development and build processes.
Workspace Configuration
The monorepo defines three workspace categories in package.json5-8:
| Workspace Pattern | Purpose | Example Packages |
|---|---|---|
packages/* | Core reusable packages published to npm | @excalidraw/common, @excalidraw/excalidraw |
excalidraw-app | Hosted application at excalidraw.com | Application with collaboration features |
examples/* | Integration examples and demos | Browser integration examples |
Sources: package.json1-9 tsconfig.json20-32
The monorepo contains five core packages with strict dependency ordering to prevent circular dependencies. This layered architecture ensures clean separation of concerns and enables independent versioning.
Package Descriptions
| Package | Location | Primary Responsibilities |
|---|---|---|
@excalidraw/common | packages/common/ | Shared constants, type utilities, common helpers |
@excalidraw/math | packages/math/ | Geometric calculations (curves, vectors, rectangles, points) |
@excalidraw/element | packages/element/ | Element data structures, binding system, delta store |
@excalidraw/excalidraw | packages/excalidraw/ | Core React library, canvas rendering, actions, UI components |
@excalidraw/utils | packages/utils/ | General-purpose utility functions |
TypeScript Path Aliases
The tsconfig.json21-31 defines path aliases for all packages, enabling clean imports:
Sources: package.json55-59 tsconfig.json20-32
The codebase produces two distinct artifacts with different purposes and feature sets:
The core library package published to npm provides a React component that can be integrated into any application. It includes:
The library is framework-agnostic in the sense that it can be embedded in any React application but does not include collaboration or persistence features.
The application in excalidraw-app/ extends the core library with additional features for the hosted service at excalidraw.com:
Build Scripts
| Script | Purpose | Packages Built |
|---|---|---|
build:packages | Build all core packages sequentially | common → math → element → excalidraw |
build:app | Build hosted application | excalidraw-app |
build:app:docker | Build for Docker deployment | excalidraw-app (optimized) |
Sources: README.md58-88 package.json51-65
The following diagram shows how the major components interact at runtime:
Key Components
ExcalidrawElement objects representing the drawingSources: package.json1-94 README.md1-131 tsconfig.json1-36
The monorepo uses modern JavaScript tooling for development and production builds:
Development Commands
| Command | Description |
|---|---|
yarn start | Start Vite dev server for excalidraw-app |
yarn test | Run Vitest tests |
yarn test:typecheck | Run TypeScript compiler for type checking |
yarn test:code | Run ESLint on all TypeScript/JavaScript files |
yarn build:packages | Build all packages in dependency order |
Sources: package.json46-89 tsconfig.json1-36
Excalidraw is distributed through multiple channels:
The @excalidraw/excalidraw package is published to npm for integration into other applications. The release process is managed by scripts/release.js with support for multiple channels:
| Release Channel | npm Tag | Purpose |
|---|---|---|
release:test | test | Experimental builds |
release:next | next | Pre-release versions |
release:latest | latest | Stable releases |
The hosted application is containerized using a multi-stage Docker build defined in Dockerfile1-21:
The Docker image supports multiple architectures (amd64, arm64, arm/v7) and is published to DockerHub via .github/workflows/publish-docker.yml1-31
The application at excalidraw.com is built using yarn build:app and deployed as a static site with:
Sources: Dockerfile1-21 .github/workflows/publish-docker.yml1-31 package.json83-86 docker-compose.yml1-23
Refresh this wiki