At its heart, a tldraw canvas is not just a blank space for pixels. It's a sophisticated, local-first database designed for managing and curating media. Think of it as an 'Alchemical Vessel'—a place where you don't just view content, but actively transform and arrange it. This entire system is managed by three core components working in concert: the Editor, the Store, and the Canvas.

The Editor is your command center. It provides a comprehensive API surface for all interactions, from creating a shape to panning the camera. The Store is the single source of truth—a reactive database holding the state of every single element. The Canvas is the renderer, responsible for turning the data in the Store into the visual output you see on the screen.

Everything that exists on a tldraw canvas is a record in the Store. A shape isn't just a collection of pixels; it's a structured data object. The camera's position, the current page, and even user presence information for multiplayer sessions are all stored as distinct records. This 'database-first' approach is the key to tldraw's power and flexibility.

The Store contains different types of records, each with a unique, stable ID. The core types include shape, camera, page, instance, and document. Each record is an immutable object. When something changes, we don't modify the existing record; we create a new version. This immutable pattern is fundamental to how the reactive system works.

This structure ensures that the canvas is always a direct reflection of the data in the Store. There is no other hidden state to worry about.

How does the canvas know when to re-render? This is handled by a signal-based reactivity library called Signia . When you interact with the canvas via the Editor API, the Store updates its records. Signia detects this change and notifies any parts of the application that are 'subscribed' to that specific piece of data. The renderer, being a subscriber, then repaints only the parts of the canvas that were affected.

This signal-based approach is incredibly efficient. Instead of re-rendering the entire canvas on every change, tldraw can pinpoint exactly which shape needs updating, leading to consistently high performance. It also powers the developer experience, allowing you to create reactive UIs that respond to changes in the canvas state with minimal code.

One of the key architectural philosophies of tldraw is being 'local-first.' This means your data lives on your device by default, and the application works perfectly offline. The network is treated as an enhancement for features like collaboration, not a requirement for the app to function.

The Store architecture makes this straightforward. Persisting the state of the canvas is as simple as saving the collection of records from the Store to a local database like IndexedDB. When the user re-opens the application, you can load these records back into the Store, and the canvas will be restored to its exact previous state.

This strategy gives users ownership and control over their data, ensuring privacy and providing a resilient, offline-capable experience. It’s a powerful foundation that makes building complex, reliable applications on top of the tldraw SDK much easier.

Time to check your understanding of tldraw's core architecture.

Understanding these core components—the Editor, the Store, and the signal-based reactivity that connects them—is the first step to mastering the tldraw SDK. With this foundation, you can build powerful and performant canvas-based applications.