File formats and export

Purpose

How tldraw documents are serialized, exchanged, and converted: the .tldr file format, image/SVG export, clipboard, and the external-content pipeline (drop/paste/embed).

.tldr files

A .tldr file is a JSON serialization of a StoreSnapshot. The schema version is included, so the file is portable across SDK versions: loading runs migrations.

• Write: editor.store.getStoreSnapshot() → JSON.
• Read: editor.store.loadSnapshot(snapshot) (runs migrations).
• Helpers: packages/tldraw/src/lib/utils/tldr/ ships read/write helpers used by the dotcom client and the VS Code extension.

The VS Code extension treats .tldr files as the canonical persistent format. The dotcom client supports import/export via the file menu.

Image export

Image export goes through Editor.toImage(...) (see packages/editor/src/lib/editor/Editor.ts) and the SVG/PNG helpers under packages/tldraw/src/lib/utils/export/ and packages/tldraw/src/lib/utils/svg/.

graph LR
    Shapes -->|getGeometry, toSvg| ShapeUtil
    ShapeUtil -->|SVG nodes| SVG[<svg>]
    SVG -->|optional| PNG[rasterize to PNG]
    SVG -->|download| User

Each ShapeUtil returns its SVG via toSvg(). The editor composes the per-shape SVGs into a document SVG with the right viewport and styles. PNG export rasterizes the SVG via the platform's OffscreenCanvas or a temporary canvas.

Clipboard

packages/tldraw/src/lib/utils/clipboard.ts plus the useClipboardEvents hook handle copy, cut, and paste. Copy formats include:

• text/html — for paste into rich-text editors.
• image/png — for paste into image editors.
• The application-specific format with the full snapshot, so paste round-trips back into tldraw.

External content

packages/tldraw/src/lib/defaultExternalContentHandlers.ts (24 KB) is the canonical map from "external content" (drag, paste, drop) to "shape created in the editor":

Source	Becomes
Image file	image shape with an asset uploaded via the asset store.
Video file	video shape.
URL (drag/paste)	bookmark shape (or embed if the URL matches a known embed).
Plain text	text shape (or paste into editing shape).
.tldr snapshot	loadSnapshot into the current page.
SVG file	One image shape per file.
Excalidraw export	Imported via packages/tldraw/src/lib/utils/excalidraw/.

defaultEmbedDefinitions.ts (22 KB) lists the recognized embed providers (YouTube, Figma, GitHub, CodePen, Codesandbox, Replit, Spotify, etc.), each with a transform from a public URL to the embeddable iframe URL.

Custom apps replace any of this via the <Tldraw /> assetUrls, onMount, or externalContentHandlers props.

Asset storage

Assets (images, videos, bookmarks) live in TLAsset records, but the actual blobs are stored elsewhere. The editor uses an AssetStore strategy:

• inlineBase64AssetStore — embed blobs as data URLs (small documents only).
• A custom store — upload to S3, R2, your own server, etc.

The dotcom client uses apps/dotcom/asset-upload-worker as its asset store. Resized variants are served by apps/dotcom/image-resize-worker.

Related

• Store and migrations
• @tldraw/tldraw
• apps/dotcom