tldraw

Last reviewed Aug 26, 2026 · 857 words

tldraw is not a whiteboard you install; it is a TypeScript library you build a whiteboard with. There is no official Docker image that gives you a Miro replacement on port 3000, and if that is what you came for, Excalidraw ships one and you should go use it. What tldraw offers instead is the best infinite canvas available as a component, 49,960 GitHub stars' worth of polish, and a multiplayer sync layer you can run yourself. The self-hosting question is really "am I prepared to write about 40 lines of React and run a small WebSocket server," and the answer decides everything.

Which product you actually want

Excalidraw is a finished app whose source you can also embed. tldraw is an SDK whose finished app (tldraw.com) is not the thing you self-host. Everything below assumes you are in the second column.

The minimum client is one component

npm create vite@latest board -- --template react-ts
cd board && npm install tldraw

import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <Tldraw persistenceKey="team-board" />
    </div>
  )
}

That is a working single-user whiteboard. persistenceKey saves the document to the browser's IndexedDB, so it survives reloads but lives on one machine. Run npm run build and serve the dist/ folder from any static host; it needs nothing on the server side. For a personal scratch canvas, stop here and be happy.

Multiplayer means running the sync server yourself

Shared live editing is what @tldraw/sync is for. The client side is a hook:

import { useSync } from '@tldraw/sync'

const store = useSync({ uri: 'wss://board.example.com/connect/room-1', assets })
return <Tldraw store={store} />

The server side is where the self-hosting actually happens. tldraw's reference sync server targets Cloudflare Workers with Durable Objects, which is convenient if you already live there and useless if you want it on your own box. The repository also carries a plain Node example server that keeps each room in memory, flushes it to disk on an interval, and speaks the same protocol, and that is the one to start from for a homelab. Expect to write three things: room persistence (a file per room or a PostgreSQL row per room is enough), an auth check on the WebSocket upgrade, and an asset store for pasted images and videos, because those are uploaded separately from the document and the SDK gives you the TLAssetStore interface rather than an implementation. Point it at MinIO or a directory behind your web server. The catalogue's 512 MB RAM figure is realistic: the Node process is tiny and memory scales with open rooms.

Put Caddy in front with websocket pass-through. Every reverse proxy handles this, but it is the first thing to check when collaboration silently fails while the page loads fine.

The watermark is a licence term, not a bug

A "made with tldraw" mark sits in the corner of the canvas unless you supply a key through the licenseKey prop. It is small, and tldraw states the terms on tldraw.dev, which at last check offered free keys for non-commercial and small projects and a paid business licence beyond that. For a homelab board nobody minds. For a product you sell, read the terms before you build, because removing the mark by editing the source is exactly what the licence forbids.

Why builders still pick tldraw over Excalidraw

Custom shapes. A tldraw shape is a React component with its own props, geometry and handles, so a Kanban card, a live chart or an embedded video player can sit on the canvas and behave like a native object. The editor API lets you script the canvas from outside: create shapes from data, subscribe to changes, export a selection to SVG or PNG. Excalidraw exposes some of this, but its shape vocabulary is fixed and hand-drawn on purpose. If your whiteboard is the product, tldraw's canvas feels like a professional tool and Excalidraw's feels like a sketch. If your whiteboard is a place to sketch, that is the point of Excalidraw.

What I'd do

For a team that just needs a shared board: Excalidraw in Docker, done in 10 minutes, revisit in a year. For anything you are building: the Vite scaffold above, persistenceKey until you have proven the idea, then @tldraw/sync with the Node example server on your own hardware, rooms persisted to a directory, assets on MinIO, Caddy in front. Budget an afternoon for the sync server and an hour reading the licence page. tldraw rewards builders and frustrates people who expected an app; be honest about which one you are before you clone the repo.