tldraw migration assistant

tldraw migration assistant

You are helping migrate a project to a newer version of the tldraw SDK. Follow this process carefully.

Throughout this skill, ${SKILL_DIR} refers to this skill's own directory (where SKILL.md, the helper .mjs scripts, and the cached references/ folder live). The auto-fetch blocks below resolve it from the SKILL_DIR env var if set, otherwise probe the common skill locations (.claude/skills/, .agents/skills/, .codex/skills/, .cursor/skills/, skills/). When you run shell commands later in the workflow that reference ${SKILL_DIR}, substitute the same absolute path. If you placed this skill somewhere else, set SKILL_DIR before running the auto-fetch blocks.

Arguments: /tldraw-migrate [from-version] [target]. Both optional. from-version defaults to the previous tldraw version detected from git history. target defaults to latest (the latest stable release on npm); pass a dist-tag (canary, next, beta) or a pre-release semver (e.g. 4.6.0-canary.abc123) to migrate to a pre-release.

Resolved migration: !SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && FROM=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS || true) && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && if [ -z "$FROM" ]; then echo "ERROR: could not detect previous tldraw version. Pass it explicitly: /tldraw-migrate <from-version> [target]" >&2; else echo "from $FROM → target $TARGET"; fi

Resources (auto-fetched on invocation)

The three blocks below are written for Claude Code's !-prefix auto-execute syntax. If you are an agent that doesn't auto-run these (Cursor, Codex, plain Claude, etc.), execute each one as a shell command before continuing — they download the changelog, full docs, and (for pre-release targets) next-release notes that the rest of the workflow depends on.

!SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && CHANGELOG="$SKILL_DIR/references/tldraw-releases.txt" && PREV=$(node "$SKILL_DIR/detect-versions.mjs" $ARGUMENTS || true) && if [ -z "$PREV" ]; then echo "ERROR: could not detect previous tldraw version — skipping changelog fetch. Pass it explicitly: /tldraw-migrate <from-version> [target]" >&2; else node "$SKILL_DIR/fetch-release-notes.mjs" "$PREV" > "$CHANGELOG" && echo "Saved changelog (from $PREV, sourced from github.com/tldraw/tldraw) to $CHANGELOG ($(wc -l < "$CHANGELOG") lines)"; fi

!SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && DOCS="$SKILL_DIR/references/tldraw-full-docs.txt" && STALE=$(find "$DOCS" -mtime +30 2>/dev/null) && if [ -s "$DOCS" ] && [ -z "$STALE" ]; then echo "Using cached full docs at $DOCS ($(wc -l < "$DOCS") lines) — delete the file or wait 30 days to refresh"; else curl --fail -sS https://tldraw.dev/llms-full.txt -o "$DOCS" && echo "Saved full docs to $DOCS ($(wc -l < "$DOCS") lines)"; fi

!SKILL_DIR="${SKILL_DIR:-$(for d in .claude/skills/tldraw-migrate .agents/skills/tldraw-migrate .codex/skills/tldraw-migrate .cursor/skills/tldraw-migrate skills/tldraw-migrate; do [ -d "$d" ] && printf %s "$d" && break; done)}" && mkdir -p "$SKILL_DIR/references" && TARGET=$(node "$SKILL_DIR/detect-target.mjs" $ARGUMENTS) && case "$TARGET" in canary|next|beta|alpha|rc|*-canary*|*-next*|*-beta*|*-alpha*|*-rc*) NEXT="$SKILL_DIR/references/tldraw-next.mdx" && curl --fail -sS https://raw.githubusercontent.com/tldraw/tldraw/main/apps/docs/content/releases/next.mdx -o "$NEXT" && echo "Pre-release target ($TARGET) — saved next-release notes to $NEXT ($(wc -l < "$NEXT") lines)" ;; *) echo "Stable target ($TARGET) — skipping next-release notes" ;; esac

• Filtered changelog — release notes for stable versions between the previous version and now, pulled directly from apps/docs/content/releases/ on tldraw/tldraw main (GitHub is the source of truth, not tldraw.dev). Each breaking change (marked 💥) carries a <details><summary>Migration guide</summary> block with a before/after recipe. These migration blocks are the primary source for version-specific fixes — this skill intentionally does not duplicate them. When you hit a TS error, grep for the relevant API name in this file and read its migration block.
• Full docs — complete tldraw SDK docs (~1.5MB). Do NOT read this upfront. Use Grep or Read with line ranges to search for specific topics as needed (e.g., custom shapes, TLTextOptions).
• Next-release notes — only present when the target is a pre-release. The in-progress release notes (raw MDX from main) for the upcoming version. Same <details><summary>Migration guide</summary> structure. The stable changelog won't cover canary/next deltas; this file is where you'll find them.

Searching for migration recipes:

Always grep both the stable changelog and next.mdx (the latter only exists for pre-release targets — 2>/dev/null swallows the missing-file warning). Migration blocks routinely run 40–80 lines, so use -A60 as the default after-context.

# List every breaking change with a migration block
grep -nE '💥|<summary>Migration guide' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx 2>/dev/null

# Find the migration recipe for a specific symbol
grep -n -B2 -A60 'getIndicatorPath\|TLUserStore\|EmbedShapeUtil' ${SKILL_DIR}/references/tldraw-releases.txt ${SKILL_DIR}/references/tldraw-next.mdx 2>/dev/null

Step 1: Understand the environment

Before making any changes, scan the project to understand what you're working with. Run these in parallel: