@bencejdanko/tldraw-astro

A robust integration for rendering tldraw diagrams in Astro projects using standard Markdown directives.

Features

- 🎨 Standard Markdown syntax: Use ::tldraw{src="diagram.json"} in any .md or .mdx file.
- 📦 Co-located Assets: Support for relative paths to diagrams in the same folder.
- 🚀 Zero-Config Integration: One-line setup in astro.config.mjs.
- 🔧 Automatic Hydration: Handles client-side loading of diagrams automatically.
- 🎯 Type-safe: Full TypeScript support.
- 🎪 Graceful Fallbacks: Beautiful error states for missing or invalid diagrams.

Installation

``bash
pnpm add @bencejdanko/tldraw-astro tldraw react react-dom
`

Setup

Add the integration to your astro.config.mjs:

`javascript
import { defineConfig } from "astro/config";
import tldraw from "@bencejdanko/tldraw-astro";

export default defineConfig({
integrations: [
tldraw({
defaultHeight: 600, // Optional: default is 600
defaultInteractive: false // Optional: default is false
}),
],
});
`

You must manually add the appropriate stylesheets to your HTML and layouts. For example, add the below line to your layout.astro file:

`html

`

Usage

In any Markdown file, use the ::tldraw directive:

`markdown


My Diagram


::tldraw{src="./architecture.json"}


::tldraw{src="/diagrams/flow.json"}


::tldraw{src="diagram.json" height="800" interactive="true" class="my-custom-style"}
`

API Reference

$3

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| src | string | required | URL or path to the tldraw JSON file |
| height | number | 600 | Canvas height in pixels |
| interactive | boolean | false | Enable zoom, pan, and UI controls |
| class | string | "" | Additional CSS classes |

$3

`typescript
interface TldrawAstroConfig {
defaultHeight?: number; // Default height if not specified in directive
defaultInteractive?: boolean; // Default interactivity if not specified
}
`

Development

`bash


Build the library

pnpm run build

Run tests

pnpm run test
`

Publishing to npm

To publish a new version to npm:

`bash


1. Update the version in package.json

npm version patch # or minor, or major

2. Build the package

pnpm run build

3. Publish to npm

npm publish --access public

Or if you're using a scoped package and want it public

npm publish
`

Make sure you're logged in to npm first:

`bash
npm login
``

License

MIT