Lore

A timeline of how the tldraw codebase evolved. Dates are derived from git history; "appears to have been" hedges when the rationale is not directly recorded in commits.

Eras

The first commit (May 2021)

The earliest commit on main is Initial commit dated 2021-05-09, by Steve Ruiz. The repo started as a single application and grew quickly; within a few hours commits were already named "a good starter template" and "Another good stopping point".

Public SDK and tldraw.dev (2022–2023)

The repo evolved from an app into a publishable SDK. Workspace packages (@tldraw/editor, @tldraw/tldraw, @tldraw/store, @tldraw/state, @tldraw/tlschema) were extracted, and the docs site under apps/docs (Next.js) appeared to host the public API at https://tldraw.dev. The apps/examples Vite app became the primary dev loop. packages/state and packages/store were carved out as standalone reactive primitives.

Multiplayer and the dotcom architecture (2023–2024)

Multiplayer became first-class. The wire-protocol code under packages/sync-core/ and the React glue under packages/sync/ were split, and the Cloudflare-backed production sync server moved into apps/dotcom/sync-worker/. Surrounding workers — asset-upload-worker, image-resize-worker, tldrawusercontent-worker — appeared, each as its own workspace. The "tla" (tldraw app) folder/file area at apps/dotcom/client/src/tla/ was added to support signed-in users with file management.

Templates and create-tldraw (2024)

Starter templates were added under templates/ (sync, agent, chat, branching-chat, image-pipeline, shader, vue, vite, nextjs, simple-server-example, socketio-server-example, workflow), backed by packages/create-tldraw/ so npx create-tldraw@latest could scaffold any of them.

Zero-cache and Postgres (Q1 2026)

apps/dotcom/zero-cache/ was added to host the Zero view-syncer that replicates the Postgres-backed app database to clients. Recent churn includes apps/dotcom/zero-cache/flyio-view-syncer.template.toml (17 commits in 90 days) and flyio-replication-manager.template.toml (19 commits), plus the operational fix in commit 15caa2104 ("wait for migrations before starting zero-cache in dev"). The latest fly.io rollout scaled the view-syncer to seven machines (commit f43f2cd36).

Tooling overhaul: oxlint and oxfmt (2025–2026)

The repo migrated lint and format off ESLint and Prettier (or layered on top of them) onto the Oxc toolchain. oxlint, oxfmt, and oxlint-tsgolint now run from the root scripts. The custom ESLint rules under internal/config/eslint-plugin/ (referenced in eslint.config.mjs) capture project-specific lints like tldraw/no-export-star. lint-staged runs oxfmt on commit.

MCP and the AI era (2025–2026)

apps/mcp-app/ ships a Model Context Protocol server, exposing tldraw functionality to AI clients. templates/agent/, templates/chat/, templates/branching-chat/, and templates/image-pipeline/ showcase canvas + LLM patterns. The docs site advertises "AI integrations" as a top-level feature (see the README).

Longest-standing parts

• The Editor class in packages/editor/src/lib/editor/Editor.ts has been the core surface area since the SDK split. It is also the most actively edited file (28 commits in 90 days).
• The reactive primitives in packages/state/ (Atom, Computed, transactions) have been stable for years and are now reused by external projects via the @tldraw/state npm package.
• The shape model (TLBaseShape and the family of shape records under packages/tlschema/src/shapes/) has weathered multiple major refactors but the shape-util pattern (geometry + render + handles + export) has remained the backbone.

Major rewrites and notable migrations

• Migration framework. packages/store/src/lib/migrate.ts and packages/tlschema/src/store-migrations.ts codify the migration system. The migration tests in packages/tlschema/src/migrations.test.ts are 66 KB — every schema change ships with a migration test.
• Public API discipline via api-extractor. api-report.api.md files exist at every package root and are regenerated via yarn build-api. The reports are in the worktree (most-changed files in 90 days) and are reviewed with each PR that touches a public surface.
• React 19 support. The peer ranges allow ^19.2.1 alongside ^18.2.0. Devtools were bumped to @types/react ^19.2.7.
• Yarn 4. The repo runs Yarn 4.12.0 with PnP-style workspaces but uses node_modules linker (it has a real node_modules setup and a yarn.lock file). Patches for domino and @microsoft/tsdoc are checked in under .yarn/patches/.

Deprecated or replaced

• The old, hand-written sync server appears to have been replaced by Cloudflare Durable Objects + R2 (via apps/dotcom/sync-worker/). The original demo server lives on as apps/bemo-worker/ (used by useSyncDemo).
• The npm canvas dependency was replaced with an empty package via the resolutions entry in package.json. Comment in the file: "our examples app depends on pdf.js which pulls in canvas as an optional dependency. it slows down installs quite a bit though, so we replace it with an empty package."

Growth signals

• The contributor count is heavily concentrated: top four committers (Steve Ruiz, Mitja Bezenšek, Mime Čuvalo, David Sheldrick) account for the bulk of all commits, but the long tail includes >50 outside contributors.
• External PRs are currently paused (see CONTRIBUTING.md): the project explains this is "a temporary policy until GitHub provides better tools for managing contributions" (issue 7695).
• The repo has accumulated 5,707 commits over almost five years (2021-05 → 2026-04).