Build, test, and self-host Excalidraw
Run the monorepo, build packages, test changes, and understand self-hosting boundaries.
Use this guide to take a checked-out Excalidraw monorepo from dependencies to a tested local change. It covers the commands documented by the repository; self-hosting requires you to provide and operate any services your deployment needs.
Before you begin
Install Node.js 18 or later, Yarn, and Git. The repository uses Yarn 1.22.22 and workspaces for excalidraw-app, packages/*, and examples/*. Clone the repository and work from its root.
Development flow
The app development server and package builds are separate concerns: yarn start runs the app, while package scripts build individual workspace outputs.
Run the monorepo
Clone the repository and install workspace dependencies:
git clone https://github.com/excalidraw/excalidraw.git
cd excalidraw
yarnThe workspace dependencies are available to the app and packages.
Run yarn start. The development app is available at http://localhost:3000. Open it and exercise the change in the browser.
Run yarn build:packages when your change affects reusable packages. It builds common, fractional-indexing, laser-pointer, math, element, and excalidraw in dependency order. For an app-only production build, use yarn build.
Run the relevant checks: yarn test, yarn test:code, yarn test:typecheck, and yarn test:other. The output identifies the failing scope.
When validating the embedded package, run yarn start:example. The example opens at http://localhost:3001; confirm the change works in an embedding context.
Verify
A change is ready for review when the relevant checks pass, the local app or example shows the intended behavior, and the package build completes if package output changed. Use yarn test:update only when you intentionally update Vitest snapshots and review the resulting diff.
Self-hosting boundary
The repository documents local development and app builds, not a complete hosted service contract. Collaboration requires a separately configured collaboration server, and the host application owns collaboration behavior. Treat deployment infrastructure, domains, storage, authentication, and operational limits as decisions for your deployment rather than assumptions supplied by the package.
Troubleshoot common failures
If yarn fails, confirm the supported Node.js version and Yarn installation before changing lockfiles. If the app does not appear at port 3000, inspect command output for the startup error. If a package consumer sees old code, rerun yarn build:packages and verify the example uses the rebuilt workspace. If formatting checks fail, run yarn fix, review all changes, and rerun the checks.
Next steps
Read Contribute to Excalidraw for review conventions, or start with Embed Excalidraw in React.