From d328008c620fafdaa8059d5b62e4bbe9fb50f7a0 Mon Sep 17 00:00:00 2001 From: JurijRevega <56640399+JurijRevega@users.noreply.github.com> Date: Thu, 26 Mar 2026 11:43:20 +0000 Subject: [PATCH] docs: add ONBOARDING.md for new contributors Describe monorepo layout, local setup, env vars, common yarn commands, setup checks, troubleshooting, glossary, and where to read code first. --- ONBOARDING.MD | 265 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 ONBOARDING.MD diff --git a/ONBOARDING.MD b/ONBOARDING.MD new file mode 100644 index 0000000..dc82525 --- /dev/null +++ b/ONBOARDING.MD @@ -0,0 +1,265 @@ +# Excalidraw monorepo — onboarding + +## Project overview + +**Excalidraw** is an open-source, hand-drawn-style virtual whiteboard. This repository is a **Yarn workspaces monorepo** that contains: + +- The **`@excalidraw/excalidraw`** React library (what integrators install from npm). +- The **excalidraw.com web app** (`excalidraw-app/`), which uses that library and adds hosting-specific features (PWA, collaboration, etc.). +- **Shared packages** (`packages/*`) with types, math, element logic, and utilities used by the library and tests. + +If you only want to **run the product locally**, you mostly work from the repo root with `yarn install` and `yarn start`. If you want to **change the editor**, you will spend time in `packages/excalidraw/` and related packages. + +--- + +## High-level architecture + +- **`packages/excalidraw/`** — Main editor UI and public API surface published as `@excalidraw/excalidraw`. +- **`packages/common`**, **`packages/element`**, **`packages/math`**, **`packages/utils`** — Shared building blocks; the library and Vitest resolve them via path aliases (see `vitest.config.mts`). +- **`excalidraw-app/`** — Vite-based SPA that composes the library with app-only wiring (Firebase, sockets, etc.). +- **`examples/`** — Small sample apps (e.g. Next.js, script tag) showing how consumers embed the package. +- **Root** — Workspace scripts (`package.json`), TypeScript project references (`tsconfig.json`), tests (`vitest.config.mts`, `setupTests.ts`), and tooling config. + +Data flow in development: you edit package sources → Vite (in `excalidraw-app`) loads them according to workspace linking / aliases → browser shows the app. + +--- + +## Repository structure + +### Quick project map (top level) + +| Directory / file | Responsibility | +|------------------|----------------| +| `excalidraw-app/` | Full web application (Vite dev server, production build). Entry point for local “run the site.” | +| `packages/excalidraw/` | Main React component library; npm package `@excalidraw/excalidraw`. | +| `packages/common/` | Shared constants, helpers, and cross-cutting code. | +| `packages/element/` | Element model and element-related logic. | +| `packages/math/` | Geometry and math utilities for the canvas. | +| `packages/utils/` | General utilities used across packages. | +| `examples/` | Integration examples (`with-nextjs`, `with-script-in-browser`). | +| `scripts/` | Build, release, and maintenance Node scripts. | +| `dev-docs/` | Internal documentation site (separate from user-facing docs). | +| `firebase-project/` | Firebase-related project assets (when working on app backends). | +| `public/` | Static assets served or copied as needed by the app/tooling. | +| `package.json` (root) | Workspace definition and **primary commands** (`yarn start`, `yarn test`, etc.). | +| `vitest.config.mts` | Test runner config and `@excalidraw/*` path aliases. | +| `tsconfig.json` (root) | TypeScript solution / references for the monorepo. | +| `yarn.lock` | Locked dependency tree — commit changes when dependencies change. | +| `Dockerfile`, `docker-compose.yml` | Container-based run/build (optional). | +| `CLAUDE.md` | Short internal notes for AI-assisted development in this repo. | + +--- + +## Tech stack + +- **Language:** TypeScript (strict), some JavaScript in scripts. +- **UI:** React (app and library). +- **App bundler / dev server:** Vite (`excalidraw-app`). +- **Package builds:** esbuild-driven scripts per package (see root `build:*` scripts). +- **Monorepo:** Yarn 1 workspaces (`packageManager`: `yarn@1.22.22`). +- **Tests:** Vitest (+ jsdom, canvas mocks where configured). +- **Lint / format:** ESLint, Prettier (see `yarn test:code`, `yarn fix`). + +--- + +## Prerequisites + +- **Node.js** `>= 18` (see root `package.json` → `engines`). +- **Yarn Classic** `1.x` (lockfile and `packageManager` field expect **Yarn 1**; use `corepack enable` + `corepack prepare yarn@1.22.22 --activate` if you standardize versions). + +Check versions: + +```bash +node -v # expect v18.x or newer +yarn -v # expect 1.22.x +``` + +--- + +## Environment variables and secrets + +- The app is a **Vite** project: only variables prefixed with **`VITE_`** are exposed to client-side code. +- **`.env.*` files belong at the repository root** — `excalidraw-app/vite.config.mts` sets `envDir` to the parent folder so Vite reads `.env.development` / `.env.production` next to root `package.json`. +- Repo-root **`.env.development`** and **`.env.production`** are committed templates for local and prod-shaped builds. Copy or adjust locally as needed. +- For **machine-specific overrides** (tokens, ports, flags you do not want to commit), use **`.env.development.local`** or **`.env.local`** at that same **root** (see [Vite env files](https://vitejs.dev/guide/env-and-mode.html)); keep secrets out of git. + +Common categories of variables you will see: + +- **Backend URLs** — `VITE_APP_BACKEND_V2_GET_URL`, `VITE_APP_BACKEND_V2_POST_URL` (shareable link / JSON storage). +- **Collaboration** — `VITE_APP_WS_SERVER_URL` (WebSocket server; local dev often `http://localhost:3002` if you run [excalidraw-room](https://github.com/excalidraw/excalidraw-room) separately). +- **Libraries** — `VITE_APP_LIBRARY_URL`, `VITE_APP_LIBRARY_BACKEND`. +- **Firebase** — `VITE_APP_FIREBASE_CONFIG` (JSON string). Treat contents as sensitive in forks; use your own project for experiments when possible. +- **Dev UX** — `VITE_APP_PORT` (dev server port, often `3001`), `VITE_APP_ENABLE_ESLINT`, `VITE_APP_ENABLE_PWA`, etc. + +If the app starts but features fail (share link, live collaboration), check the matching `VITE_*` value first. + +--- + +## Local setup (step-by-step) + +From the **repository root**: + +```bash +cd /path/to/excalidraw +yarn install +``` + +Optional: copy env for local tweaks (only if you need overrides): + +```bash +# Example: create a local override file (do not commit secrets) +cp .env.development .env.development.local +# Edit .env.development.local as needed +``` + +Start the web app: + +```bash +yarn start +``` + +**Expected result:** Vite starts the `excalidraw-app` dev server; terminal shows a local URL (by default often **`http://localhost:3001`** if `VITE_APP_PORT=3001` in `.env.development`). Opening it loads the editor. + +--- + +## Run, test, typecheck, build commands + +Run all commands from the **repo root** unless noted. + +| Goal | Command | Notes | +|------|---------|--------| +| Dev server (main app) | `yarn start` | Runs `vite` in `excalidraw-app/`. | +| Production build (app) | `yarn build` | App build + version script. | +| Preview production build | `yarn build:preview` | Build then `vite preview` (port **5000**). | +| Build all publishable packages | `yarn build:packages` | `common` → `math` → `element` → `excalidraw`. | +| Example: script-in-browser | `yarn start:example` | Builds packages then starts `examples/with-script-in-browser`. | +| Unit / integration tests | `yarn test` | Vitest (watch mode by default). | +| Update snapshots | `yarn test:update` | `vitest --update --watch=false`. | +| Typecheck | `yarn test:typecheck` | Runs `tsc` from root `tsconfig.json`. | +| Lint | `yarn test:code` | ESLint, zero warnings. | +| Format check | `yarn test:other` | Prettier `--list-different`. | +| Auto-fix format + lint | `yarn fix` | Prettier write + ESLint fix. | +| Full local gate (heavy) | `yarn test:all` | typecheck + lint + prettier + app tests non-watch. | + +**Example — typecheck success (abbreviated):** + +```text +yarn run v1.22.22 +$ tsc +Done in 12.34s. +``` + +**Example — tests success (abbreviated):** + +```text +yarn run v1.22.22 +$ vitest + ✓ packages/excalidraw/...some.test.tsx (3 tests) 45ms + Test Files 1 passed (1) + Tests 3 passed (3) +``` + +--- + +## Where to start reading the code + +Use this order to build a mental model quickly: + +- **`excalidraw-app/index.tsx`** — Vite loads this module from `excalidraw-app/index.html`; follow imports to see how the site boots and wraps the editor. +- **`packages/excalidraw/index.tsx`** — Public entry for **`@excalidraw/excalidraw`**; re-exports the component API consumers use. +- **`packages/excalidraw/`** (components, hooks, actions) — Most UI and editor behavior lives here; search by feature name (e.g. toolbar, export, selection). +- **`packages/element/src/`** — How elements are represented, updated, and validated on the canvas. +- **`packages/math/src/`** and **`packages/common/src/`** — Low-level geometry and shared types/helpers reused everywhere. +- **`vitest.config.mts`** — Shows how **`@excalidraw/*`** imports resolve during tests (mirrors Vite aliases in `excalidraw-app/vite.config.mts`). + +**Tip:** After you know one flow (for example “export to PNG”), use repo search on a visible string or symbol from the UI to jump straight to the handler. + +--- + +## Setup validation + +After `yarn install`: + +1. **Dependencies installed** + + ```bash + ls node_modules | head + ``` + + **Expected:** Directory listing including `.bin`, `@types`, etc. + +2. **TypeScript compiles** + + ```bash + yarn test:typecheck + ``` + + **Expected:** Exit code **0**, no `error TS` lines, ends with `Done in …s`. + +3. **Dev server** + + ```bash + yarn start + ``` + + **Expected:** Log line with **Local:** `http://localhost:/` (port from `VITE_APP_PORT`, default commonly **3001**). Browser shows Excalidraw. + +4. **Tests (smoke)** + + ```bash + yarn test:app run + ``` + + **Expected:** Vitest runs **once** (no watch), then exits with passed tests (or use `yarn test:update` when intentionally refreshing snapshots). + +Stop the dev server with `Ctrl+C` in that terminal. + +--- + +## Troubleshooting + +| Problem | What to try | +|---------|-------------| +| `yarn: command not found` | Install Yarn 1 globally or via Corepack; reopen shell. | +| `tsc: command not found` when running `yarn test:typecheck` | Run `yarn install` from repo root; `typescript` is a root `devDependency`. | +| Wrong Node version / odd native errors | Use Node **18+**; switch with `nvm`, `fnm`, or `asdf`. | +| `EACCES` or permission errors in `node_modules` | Remove root `node_modules`, fix npm/yarn global prefix permissions, reinstall. | +| Port already in use (`EADDRINUSE`) | Change `VITE_APP_PORT` in `.env.development` or `.env.development.local`, or stop the other process. | +| Blank screen / env not applied | Ensure vars are prefixed with `VITE_`; restart dev server after editing `.env*`. | +| Collaboration / WS features do not work | Set `VITE_APP_WS_SERVER_URL` to a running [excalidraw-room](https://github.com/excalidraw/excalidraw-room) instance or expect those features to be disabled offline. | +| Stale package output after editing `packages/*` | Run `yarn build:packages` or use `yarn start:example` flow; for app dev, Vite usually picks up sources—if not, clear caches / restart dev server. | +| ESLint errors in editor only | Run `yarn fix`; ensure IDE uses workspace ESLint + Prettier settings. | +| Test snapshot failures | If changes are intentional, `yarn test:update`; otherwise fix code or snapshots deliberately. | + +--- + +## Glossary + +| Term | Meaning | +|------|---------| +| **Workspace** | Yarn monorepo package; each folder under `packages/*`, `excalidraw-app`, `examples/*` with its own `package.json`. | +| **`@excalidraw/excalidraw`** | Published npm name for the main React library in `packages/excalidraw`. | +| **`excalidraw-app`** | The full product shell at excalidraw.com in this repo—not the same as the npm package alone. | +| **Element** | A shape or object on the canvas (rectangle, arrow, text, etc.) and its serialized data. | +| **Scene** | The current document state: elements, appState, and related data the editor renders. | +| **Vite** | Frontend toolchain used to serve and bundle `excalidraw-app`. | +| **`VITE_*` variable** | Build-time environment variable exposed to browser code (Vite convention). | +| **Vitest** | Test runner used across the monorepo (`vitest.config.mts`). | +| **Path alias** | Import shortcut like `@excalidraw/common` mapped to `packages/common/src` in tests/build configs. | + +--- + +## Useful links + +- **User & integration docs:** [https://docs.excalidraw.com](https://docs.excalidraw.com) +- **Development guide (official):** [https://docs.excalidraw.com/docs/introduction/development](https://docs.excalidraw.com/docs/introduction/development) +- **Contributing:** [https://docs.excalidraw.com/docs/introduction/contributing](https://docs.excalidraw.com/docs/introduction/contributing) +- **Collaboration server (reference):** [https://github.com/excalidraw/excalidraw-room](https://github.com/excalidraw/excalidraw-room) +- **This repo’s quick structure note:** `CLAUDE.md` (root) + +--- + +## Document owner + last updated + +- **Owner:** Team maintaining this repository — keep this file accurate when scripts, ports, or layout change. +- **Last updated:** 2025-03-26