The tldraw repository is an infinite canvas SDK and ecosystem for building drawing, diagramming, and whiteboarding applications. This page introduces the repository's structure, the SDK packages, reference applications, and supporting backend infrastructure.
tldraw is an infinite canvas SDK for React that provides a complete whiteboarding engine. The repository contains:
@tldraw/editor, tldraw, @tldraw/store, etc.) for building canvas applications. packages/tldraw/package.json2-4 packages/editor/package.json2-4dotcom web app, VS Code extension, and an MCP (Model Context Protocol) application. package.json28-35 apps/dotcom/client/package.json2-4sync-worker), asset storage, and deployment tooling for the dotcom application. apps/dotcom/client/package.json31-60lazyrepo, CI/CD pipelines, and testing infrastructure. package.json111 package.json36-79The SDK is framework-agnostic at its core (@tldraw/editor), with React bindings and UI components provided in the tldraw package. Applications can use the complete SDK with default UI or build custom experiences using lower-level primitives.
Sources: README.md16-33 packages/tldraw/package.json1-30 packages/editor/package.json1-30
The tldraw ecosystem consists of three primary layers: SDK packages, applications, and backend infrastructure. This diagram shows how these components relate:
Ecosystem Overview
The SDK provides the canvas engine and data layer. Applications consume the SDK packages. The dotcom application additionally uses backend services for multiplayer sync and persistence. For a deeper look at the system design, see Architecture Overview.
Sources: README.md1-50 packages/tldraw/package.json54-70 packages/editor/package.json49-65 package.json28-35 apps/dotcom/client/package.json31-60
The repository is organized as a Lerna + Yarn Workspaces monorepo using lazyrepo for task orchestration. package.json28-35 lerna.json1-7
| Directory | Purpose | Key Contents |
|---|---|---|
packages/ | SDK packages | @tldraw/editor, tldraw, @tldraw/tlschema, @tldraw/mermaid, @tldraw/driver |
apps/ | Applications | dotcom, examples, vscode, mcp-app |
templates/ | Starter kits | agent, workflow, sync-cloudflare, shader, create-tldraw |
internal/ | Build tooling | Build scripts, CI/CD configuration, huppy bot |
For a detailed breakdown of the workspace organization and new packages like create-tldraw, see Repository Structure.
Sources: package.json28-35 lerna.json1-7 yarn.lock1-10 packages/tldraw/package.json62-64
The Editor class is the central coordinator for the canvas. It manages the state of the canvas, processes inputs, and coordinates various manager subsystems.
Editor Core Components
The Editor accepts options specifying the TLStore, shape utilities, and tools. React components provide the editor instance via context. Detailed documentation of the Editor class and its subsystems can be found in the Core SDK section.
Sources: packages/editor/package.json49-65 packages/tldraw/package.json54-70 packages/editor/package.json29-30
The @tldraw/state package provides reactive primitives, while @tldraw/store implements TLStore for managing records like TLShape and TLBinding. packages/state/package.json2-3 packages/store/package.json2-3
Shapes are visual elements defined by ShapeUtil classes. Bindings connect shapes together, such as arrows connecting to boxes, managed by BindingUtil. README.md23-34
tldraw includes first-class support for AI agents. The agent template and tldraw-agent primitives allow developers to build LLM-powered tools that can read and modify the canvas README.md69-74 The @tldraw/mermaid package facilitates converting text-based Mermaid diagrams into editable tldraw shapes apps/dotcom/client/package.json39 The mcp-app enables AI agents to interact with the canvas via the Model Context Protocol.
Sources: README.md23-34 packages/tlschema/package.json52-57 apps/dotcom/client/package.json39-40
To begin developing with tldraw:
npx create-tldraw@latest to scaffold a new project with various templates (Multiplayer, Agent, Workflow, Shader). README.md65-66yarn to install dependencies, and yarn dev to start the examples application at localhost:5420. README.md75-88lazyrepo task orchestration. README.md96-98For full instructions, see Getting Started.
Sources: README.md35-56 README.md65-74 README.md75-88 package.json42-47
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.