# Project pack: Excalidraw @ 1d4dc2c

Facts about **Excalidraw** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Excalidraw is a blank digital whiteboard where you draw boxes, arrows, notes and doodles that look as if they were sketched by hand. Use it to plan a garden, map out a family tree, sketch a room layout or explain an idea. Drawings save in your browser automatically and you can export them as pictures or files. You can use the free official site, or run your own copy at home with one Docker command.

## Version and source
- Repository: https://github.com/excalidraw/excalidraw
- Pinned commit: `1d4dc2c0e6e476911d0760e9c3cf3694f2d43384`. Use exactly this version.
- Get it: `git clone https://github.com/excalidraw/excalidraw excalidraw && cd excalidraw && git checkout 1d4dc2c0e6e476911d0760e9c3cf3694f2d43384`
- Or download a zip: https://github.com/excalidraw/excalidraw/archive/1d4dc2c0e6e476911d0760e9c3cf3694f2d43384.zip
- Official docs: https://docs.excalidraw.com
- Live demo: https://excalidraw.com. The official free app, built from this repository. Drawings stay in your browser unless you share them.
- Licence: **MIT**. Very permissive. Use, change and share it for anything, including commercially. Just keep the copyright and licence notice with the code. No obligation to publish your changes.

## Running it
- Easiest:

  ```sh
  docker run --rm -dit --name excalidraw -p 5000:80 excalidraw/excalidraw:latest # then open http://localhost:5000
  ```

- Needs: Docker, or any static web host, For development, Node.js 18 or newer, Yarn 1 and Git
- Develop: `yarn && yarn start   # opens on http://localhost:3001 (VITE_APP_PORT in .env.development)`
- Test: `yarn test:typecheck && yarn test:update`
- Check/lint: `yarn test:code && yarn test:other   # yarn fix auto-fixes formatting and lint`
- Build: `yarn build:app:docker   # static files in excalidraw-app/build`
- Stack: typescript, scss (React 19, Vite, Jotai, Vitest, Yarn workspaces). Difficulty for a non-developer with an AI: **moderate**. No server or database to manage: the app is a set of web files. But it is a large TypeScript monorepo. The editor itself lives in packages/excalidraw/ and the excalidraw.com shell (welcome screen, menus, sharing) in excalidraw-app/. Small changes to text, colours and the welcome screen are approachable; canvas and drawing changes are hard.

## The project's own AI instructions
Read these in the repository before changing code: `CLAUDE.md`, `AGENTS.md`.

## Customisation points (settings → extend → code)
- **theme-and-canvas** [settings]: Light or dark mode, background colour and one of dozens of interface languages, all from the menu. → `Main menu (excalidraw-app/components/AppMainMenu.tsx) → theme, canvas background, language`
- **shape-libraries** [settings]: Add ready-made shapes such as furniture, garden plants or icons, or save your own reusable pieces. → `Library sidebar → Browse libraries (packages/excalidraw/components/LibraryMenu.tsx, packages/excalidraw/data/library.ts)`
- **own-servers** [extend]: Point sharing, collaboration and AI at your own servers (or leave them blank) and rebuild the image. → `Build-time variables in .env.production (typed in excalidraw-app/vite-env.d.ts); collaboration client in excalidraw-app/collab/Collab.tsx`
- **file-format-and-embedding** [extend]: Generate drawings from a script, or embed the whiteboard inside another web page or app. → `.excalidraw JSON format (dev-docs/docs/codebase/json-schema.mdx, packages/excalidraw/data/json.ts); npm package @excalidraw/excalidraw (packages/excalidraw/index.tsx, examples/)`
- **mermaid-import** [extend]: Paste a Mermaid flowchart (which any chat AI can write for you) and turn it into an editable drawing, without the AI server. → `More tools → Mermaid to Excalidraw (packages/excalidraw/components/TTDDialog/MermaidToExcalidraw.tsx)`
- **welcome-and-menu** [code]: Change the welcome screen heading and menu items, or remove the Excalidraw+ links. → `excalidraw-app/components/AppWelcomeScreen.tsx, excalidraw-app/components/AppMainMenu.tsx, excalidraw-app/components/ExcalidrawPlusPromoBanner.tsx`
- **text-and-colours** [code]: Reword labels, change the colour swatches offered, or add a font. → `packages/excalidraw/locales/en.json (wording), packages/common/src/colors.ts (colour palette), packages/excalidraw/fonts/index.ts (fonts)`
- **editor-behaviour** [code]: New tools, actions and drawing behaviour. Large, central files; read CLAUDE.md first. → `packages/excalidraw/components/App.tsx, packages/excalidraw/actions/, packages/element/src/`

## Must keep working
- Existing drawings saved in the browser and in .excalidraw files. They must still open after any change (packages/excalidraw/data/restore.ts handles older files).
- End-to-end encryption of shared and collaborative drawings. Keys stay in the link after the
- Works offline as an installable app (PWA) once loaded.
- Keep the MIT copyright and licence notice.

## Staying updatable
Most personal use needs no code: settings, libraries, files and Mermaid import cover a lot. For code changes, follow CLAUDE.md and AGENTS.md, keep edits to excalidraw-app/ where you can (it changes less than the editor), and run yarn test:typecheck and yarn test:update. Upstream welcomes pull requests with semantic titles (feat:, fix:).

## Data, costs and safety
- Personal data: **yes**. Stored in: In your own browser (localStorage for the drawing, IndexedDB for pasted images). Nothing is kept on the server you run. Files you save with "Save to…" are .excalidraw JSON files on your computer. Clearing your browser data deletes unsaved drawings, and each browser or device has its own copy. Save important drawings as .excalidraw files and back those up like any other document.
- Service: Excalidraw share and collaboration servers (json.excalidraw.com, oss-collab.excalidraw.com) (optional, free): Shareable links and live collaboration. Drawings are end-to-end encrypted in your browser first. Upstream says a self-hosted copy does not support sharing or collaboration yet; you can run your own collaboration server (excalidraw/excalidraw-room) and rebuild with its address.
- Service: Excalidraw AI backend (oss-ai.excalidraw.com) (optional, free, with usage limits): Optional text-to-diagram and wireframe-to-code features. Sends your prompt or the selected drawing to Excalidraw's server.
- Service: Public library catalogue (libraries.excalidraw.com) (optional, free): Browse and add ready-made shape libraries (furniture, icons, flowchart parts).
- Setting `VITE_APP_WS_SERVER_URL`: Build-time. Address of the live collaboration server. Point it at your own excalidraw-room server and rebuild.
- Setting `VITE_APP_BACKEND_V2_GET_URL`: Build-time. Where shared drawings are loaded from. VITE_APP_BACKEND_V2_POST_URL is where they are uploaded to.
- Setting `VITE_APP_AI_BACKEND`: Build-time. Server used for the AI drawing features.
- Setting `VITE_APP_LIBRARY_URL`: Build-time. The shape library website opened by "Browse libraries".
- Setting `VITE_APP_PORT`: Port for the development server (3001 in .env.development).
- The self-hosted image has no logins and stores nothing on the server, so it is safe on a home network. Put it behind HTTPS if you open it to the internet.
- Sharing links, live collaboration and AI features use Excalidraw's own servers unless you rebuild with your own. Shared drawings are encrypted in the browser first; AI prompts and selected drawings are sent to Excalidraw's AI server.
- Drawings live only in one browser. Save important ones as files so they aren't lost when browser data is cleared.

---

# Customising Excalidraw

Excalidraw is just web files: no server, no database, no accounts. That makes running your own copy easy.
The code is a big TypeScript monorepo, so **try settings, libraries and files first**.

## Level 1: Settings (no code)
- **Look:** main menu → light or dark theme, canvas background colour, interface language.
- **Shape libraries:** open the library sidebar → *Browse libraries* to add ready-made shapes (furniture, garden, icons, flowcharts). Select your own drawing and *Add to library* to reuse it.
- **Export:** PNG, SVG or copy to clipboard, with or without background, and optionally with the drawing embedded so the picture can be opened and edited again.
- **Your own copy:** `docker run -d -p 5000:80 excalidraw/excalidraw:latest`. The image has no analytics.

## Level 2: Extend (no fork)
- **Mermaid to Excalidraw** (More tools): paste a Mermaid chart and get editable shapes. Ask any chat AI to write the Mermaid for a family tree, a timeline or a to-do flow. This runs in your browser.
- **The `.excalidraw` file format** is plain JSON (`dev-docs/docs/codebase/json-schema.mdx`). A small script can generate drawings, for example a seating plan from a guest list.
- **Embed it:** the `@excalidraw/excalidraw` npm package (`packages/excalidraw/index.tsx`, examples in `examples/`) puts the whiteboard inside another web page.
- **Your own servers:** sharing, live collaboration and AI addresses are build-time variables in `.env.production` (`VITE_APP_WS_SERVER_URL`, `VITE_APP_BACKEND_V2_GET_URL` / `_POST_URL`, `VITE_APP_AI_BACKEND`). Run the separate `excalidraw/excalidraw-room` server for collaboration and rebuild the image.

## Level 3: Code
Read upstream `CLAUDE.md` and `AGENTS.md` first.

| Change | Where |
|---|---|
| Welcome screen heading and buttons | `excalidraw-app/components/AppWelcomeScreen.tsx` |
| Main menu items, Excalidraw+ links | `excalidraw-app/components/AppMainMenu.tsx`, `excalidraw-app/components/ExcalidrawPlusPromoBanner.tsx`, `excalidraw-app/App.tsx` |
| Wording | `packages/excalidraw/locales/en.json` (other languages come from Crowdin; don't edit them by hand) |
| Colour swatches | `packages/common/src/colors.ts` |
| Fonts | `packages/excalidraw/fonts/index.ts` |
| Saving in the browser | `excalidraw-app/data/LocalData.ts` |
| New tools and actions | `packages/excalidraw/actions/`, `packages/excalidraw/components/App.tsx`, `packages/element/src/` |

## Running locally
- **Just use it:** `docker run --rm -dit --name excalidraw -p 5000:80 excalidraw/excalidraw:latest`, then open http://localhost:5000.
- **Develop:**
  1. Install Node.js 18+ and Yarn 1.
  2. Run `yarn` in the repo.
  3. Run `yarn start` and open http://localhost:3001.
- **Check:** `yarn test:typecheck`, `yarn test:update` (tests with snapshot updates), `yarn fix` (formatting and lint).
- **Build your own image:** `docker build -t my-excalidraw .` (uses `yarn build:app:docker`).

## Pitfalls
- Drawings live in one browser. Save a `.excalidraw` file before clearing browser data or testing code changes.
- Old files must still open. Don't change the saved format without updating `packages/excalidraw/data/restore.ts`.
- `.env.production` is baked in at build time. Changing it does nothing until you rebuild.
- The self-hosted image still points sharing and AI at excalidraw.com unless you change those variables.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/excalidraw/1d4dc2c/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/excalidraw/1d4dc2c/SKILL.md)