@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

pnpm add @bencejdanko/tldraw-astro

Setup

Add the integration to your astro.config.mjs:

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:

<link rel="stylesheet" href="https://unpkg.com/[email protected]/tldraw.css">

Usage

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

# My Diagram

<!-- Relative paths work for co-located files! -->
::tldraw{src="./architecture.json"}

<!-- Public assets also work -->
::tldraw{src="/diagrams/flow.json"}

<!-- With custom options -->
::tldraw{src="diagram.json" height="800" interactive="true" class="my-custom-style"}

API Reference

Directive Attributes

| 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 |

Integration Options

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

Development

# Build the library
pnpm run build

# Run tests
pnpm run test

Publishing to npm

To publish a new version to npm:

# 1. Update the version in package.json
pnpm 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:

npm login

License

MIT