Assistant de migration tldraw

Vous aidez à migrer un projet vers une version plus récente du SDK tldraw. Suivez attentivement ce processus.

Version précédente (détectée automatiquement dans l'historique git ; passez une version explicite avec /tldraw-migrate <version> pour l'ignorer) : !node ${CLAUDE_SKILL_DIR}/detect-versions.mjs $ARGUMENTS

Ressources (récupérées automatiquement à l'invocation)

!mkdir -p ${CLAUDE_SKILL_DIR}/references && CHANGELOG=${CLAUDE_SKILL_DIR}/references/tldraw-releases.txt && PREV=$(node ${CLAUDE_SKILL_DIR}/detect-versions.mjs $ARGUMENTS) && curl --fail -sS https://tldraw.dev/llms-releases.txt | node ${CLAUDE_SKILL_DIR}/filter-changelog.mjs "$PREV" > "$CHANGELOG" && echo "Saved changelog (from $PREV) to $CHANGELOG ($(wc -l < "$CHANGELOG") lines)"

!DOCS=${CLAUDE_SKILL_DIR}/references/tldraw-full-docs.txt && if [ -s "$DOCS" ]; then echo "Using cached full docs at $DOCS ($(wc -l < "$DOCS") lines) — delete the file 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

Changelog filtré — notes de version entre la version précédente et maintenant. Lisez ceci en premier pour comprendre ce qui a changé.
Docs complètes — documentation complète du SDK tldraw (~1,5 Mo). Ne lisez PAS ceci d'emblée. Utilisez Grep ou Read avec des plages de lignes pour chercher des sujets spécifiques au besoin (ex. custom shapes, TLTextOptions).

Étape 1 : Comprendre l'environnement

Avant de faire des modifications, scannez le projet pour comprendre ce avec lequel vous travaillez. Exécutez ceci en parallèle :

Gestionnaire de paquets : Cherchez les fichiers de verrouillage (yarn.lock, pnpm-lock.yaml, bun.lockb, package-lock.json). Utilisez l'outil correspondant partout.
Paquets tldraw : grep -E "tldraw|@tldraw" package.json — quels paquets sont installés et à quelles versions ? Remarque : pas tout projet n'utilise tous les paquets tldraw.
Style d'import : grep -r "from '@tldraw/" src/ --include="*.ts" --include="*.tsx" -l | head -5 — le projet importe-t-il de 'tldraw', '@tldraw/editor' ou les deux ? Cela affecte les cibles d'augmentation de module.
TypeScript : Cherchez dans package.json un script typecheck ou tsc. Vérifiez aussi la version de TypeScript — est-ce une dépendance directe ou le projet s'appuie-t-il sur une installation globale ?
Outil de build : Cherchez dans les scripts package.json la commande de build (vite, next, webpack, esbuild, etc.)
Linter : Cherchez les fichiers de config eslint/biome (.eslintrc*, eslint.config.*, biome.json). Un linter peut aider à détecter les dépréciations plus tard.
Monorepo : Est-ce que package.json est à la racine du répertoire de travail, ou est-ce un paquet imbriqué ? Cherchez la config workspaces.

Étape 2 : Mettre à niveau les paquets

Utilisant le gestionnaire de paquets détecté, mettez à niveau tous les paquets tldraw déjà présents dans les dépendances du projet vers la dernière version. N'ajoutez pas de nouveaux paquets que le projet n'utilise pas déjà.

Étape 3 : Identifier toutes les erreurs TypeScript

Exécutez la commande typecheck du projet (de l'Étape 1) et catégorisez les erreurs :

Comptez les erreurs par code TS (ex. TS2344, TS2786) pour comprendre la distribution
Listez les fichiers uniques avec erreurs pour comprendre la portée
Identifiez les motifs d'erreur — catégories courantes dans les mises à niveau tldraw :
- Incompatibilité de types React (TS2786 "cannot be used as JSX component") — généralement veut dire que la version @types/react ne correspond pas à ce que tldraw embarque. Pour trouver la version embarquée : avec npm ou yarn classique, vérifiez node_modules/@tldraw/editor/node_modules/@types/react/package.json ; avec pnpm ou yarn berry, exécutez la commande « why » du gestionnaire (ex. pnpm why @types/react, yarn why @types/react) pour voir la plage résolue.
- Enregistrement de type de shape personnalisé (TS2344 "does not satisfy constraint TLShape/TLBaseBoxShape") — tldraw v4.3+ exige l'augmentation de module de TLGlobalShapePropsMap
- Enregistrement de type de binding personnalisé — même motif avec TLGlobalBindingPropsMap
- Incompatibilité de type BaseBoxShapeTool.shapeType (TS2416) — a besoin de as const
- Renommages/suppression d'API (TS2305, TS2724) — vérifiez le changelog pour les migrations spécifiques
- Élargissement de type createShapes/updateShapes (TS2345) — les tableaux mappés ont besoin de cast TLShapePartial ou TLCreateShapePartial

Étape 4 : Corriger les erreurs par ordre d'impact

Corriger dans cet ordre (chaque correction élimine de nombreuses erreurs en aval) :

4a. Corriger les types React

Si vous voyez des erreurs TS2786 "bigint not assignable to ReactNode", mettez à niveau @types/react et @types/react-dom pour correspondre à la version embarquée par tldraw.

4b. Enregistrer les shapes et bindings personnalisés

Pour chaque TLBaseShape<'name', Props> dans le codebase, ajoutez l'augmentation de module. Utilisez le style d'import détecté à l'Étape 1 comme cible du module :

declare module 'tldraw' {
    interface TLGlobalShapePropsMap {
        'shape-name': {
            /* props */
        }
    }
}
type MyShape = TLShape<'shape-name'>

Même motif pour les bindings avec TLGlobalBindingPropsMap et TLBinding<'name'>.

IMPORTANT : Si plusieurs fichiers utilisent le même nom de type de shape avec des props différentes, renommez-les pour être uniques — ils partagent tous le registre de type global.

Ajoutez as const à toutes les propriétés static override shapeType = '...'.

4c. Corriger les renommages et suppressions d'API

Croisez chaque erreur TS2305/TS2724/TS2339 avec le changelog. Motifs courants :

Exports supprimés : trouvez le remplacement en cherchant dans les définitions de type tldraw
Propriétés renommées : vérifiez le changelog pour le nouveau nom
Signatures de méthode changées : vérifiez les définitions de type actuelles

Pour trouver les définitions de type tldraw, vérifiez quels chemins existent — l'emplacement varie selon la version :

node_modules/tldraw/dist-cjs/index.d.ts
node_modules/tldraw/dist/index.d.ts
node_modules/@tldraw/editor/dist-cjs/index.d.ts
node_modules/@tldraw/tlschema/dist-cjs/index.d.ts

4d. Corriger les imports TipTap si nécessaire

Si le projet utilise TipTap (@tiptap/* dans les dépendances ou imports), la mise à niveau tldraw peut nécessiter de mettre aussi à niveau TipTap. À partir de tldraw v4.2, tldraw embarque TipTap v3 comme dépendance transitive. Si le projet épingle directement les paquets TipTap v2, cela causera des conflits de version et des imports cassés. *Mettez à niveau les dépendances directes `@tiptap/` du projet à v3** pour correspondre à ce qu'attend tldraw — les laisser sur v2 ne marchera pas.

Après la mise à niveau, corrigez tous les changements de rupture TipTap v2 → v3 :

Default → named exports : Si un import par défaut échoue, basculez à un import nommé : import StarterKit from '@tiptap/starter-kit' → import { StarterKit } from '@tiptap/starter-kit'
Renommages : Si un import nommé échoue, vérifiez les exports réels du paquet : grep 'export' node_modules/@tiptap/<package>/dist/index.js | head — certaines extensions ont été renommées dans TipTap v3 (ex. TextStyle → TextStyleKit).
Types de gestionnaire de transaction : Si les types de gestionnaire d'événement TipTap cassent, importez les bons types : import { EditorEvents } from '@tiptap/core' et typez les gestionnaires comme (props: EditorEvents['transaction']) => void plutôt que des annotations de type inline.

4e. Corriger les erreurs de type restantes

createShapes/updateShapes avec .map() : La bonne correction est d'ajouter as const au champ type dans l'objet littéral mappé pour que TypeScript le réduise au type littéral chaîne. Si ce n'est pas suffisant, utilisez une annotation satisfies sur la valeur de retour. En dernier recours seulement, castez le résultat à TLCreateShapePartial ou TLShapePartial.
Commandes d'extension TipTap absentes de ChainedCommands : utilisez l'augmentation declare module '@tiptap/core' pour enregistrer les commandes personnalisées.
Règle générale : chaque cast as que vous ajoutez est de la dette technique. Avant d'en ajouter un, épuisez ces alternatives dans l'ordre :
1. as const sur des objets littéraux pour réduire les types littéraux chaîne
2. Annotations satisfies pour vérifier les types sans élargir
3. Paramètres de type générique appropriés au site d'appel
4. Augmentation de module pour enseigner à TypeScript vos types
5. Seulement ensuite, un cast as ciblé avec un commentaire expliquant pourquoi c'est nécessaire

Étape 5 : Corriger les dépréciations

Après que toutes les erreurs de type sont résolues, trouvez et corrigez l'utilisation d'API dépréciée. Celles-ci compilent toujours mais doivent être migrées.

Trouver les symboles dépréciés — cherchez dans les définitions de type tldraw les annotations @deprecated. Cherchez aussi le changelog pour « deprecated » dans ${CLAUDE_SKILL_DIR}/references/tldraw-releases.txt.
Vérifiez si un linter est configuré — cherchez eslint, biome ou autre config de linting dans le projet. Si disponible, exécutez le linter — il peut marquer l'utilisation dépréciée automatiquement (ex. règle deprecation/deprecation d'eslint). Si aucun linter n'est configuré, passez à l'étape 3.
Cherchez le code source du projet pour chaque symbole déprécié trouvé à l'étape 1. Remplacez par l'alternative recommandée du commentaire JSDoc @deprecated ou du changelog.

Étape 6 : Vérifier

Exécutez les commandes typecheck et build du projet (découvertes à l'Étape 1).

S'il reste des erreurs, répétez le cycle catégoriser-et-corriger.

Vérification de cohérence post-migration

Après que toutes les erreurs sont résolues, faites un audit rapide :

Comptez les casts as avant vs après : Exécutez grep -rn ' as ' --include='*.ts' --include='*.tsx' src/ et comparez avec le même grep sur le code pré-migration (utilisez git stash ou git show HEAD:path). La migration ne devrait ajouter qu'une petite poignée de nouveaux casts (idéalement zéro). Si vous avez ajouté plus d'~5 nouveaux casts as dans toute la migration, revenez et corrigez-les — vous utilisez presque certainement la nouvelle API incorrectement.
Examinez chaque cast que vous avez ajouté : Pour chaque nouveau cast as, vérifiez que c'est vraiment nécessaire en vérifiant si as const, satisfies, les paramètres de type générique, ou l'augmentation de module pourraient le remplacer. Supprimez ou remplacez tous ceux qui ont une alternative plus nette.
Vérifiez aucun stub ou code mort : Si vous avez stubifié les APIs supprimées (ex. remplacé une fonction supprimée par un no-op), assurez-vous que le code qui l'appelle ne dépend pas de la valeur de retour. Si c'est le cas, trouvez le remplacement approprié dans le changelog ou les docs.

Vérifications de qualité

La sécurité des types est primordiale. L'objectif est une migration qui est aussi type-safe que le code original. N'ajoutez PAS as any, as unknown, ou des casts de type larges. N'ajoutez PAS @ts-ignore ou @ts-expect-error. Ces procédés ne sont jamais acceptables — si vous ne pouvez pas faire marcher les types, vous ne comprenez pas encore la nouvelle API. Arrêtez et lisez le changelog et les définitions de type avant de continuer.
Préférez les fonctionnalités de réduction de type de TypeScript aux casts. Utilisez as const pour les types littéraux, satisfies pour la vérification de type sans élargir, les paramètres génériques pour les sites d'appel, et l'augmentation de module pour étendre les interfaces. Ce sont les bons outils pour une migration — les casts as ne le sont pas.
Utilisez les agents parallèles pour corriger de grands lots de fichiers avec le même motif.
Ne faites pas juste disparaître les erreurs — comprenez la nouvelle API. Quand une signature de méthode change (ex. nouveaux paramètres ajoutés, propriété renommée en un type plus riche), lisez le changelog ET les définitions de type actuelles pour comprendre pourquoi cela a changé. Une correction qui compile mais passe des valeurs codées en dur/fictives où la nouvelle API attend des données réelles est pire qu'une erreur de type — cela dégrade silencieusement le comportement. Par exemple, si une fonction gagne de nouveaux paramètres requis, vérifiez quelles props de shape ou état d'éditeur devraient alimenter ces paramètres plutôt que de passer 0 ou 1.
Quand vous n'êtes pas sûr d'un motif API, cherchez dans les docs complètes (${CLAUDE_SKILL_DIR}/references/tldraw-full-docs.txt) pour les exemples d'utilisation de cette API spécifique. Les docs contiennent des échantillons de code qui montrent la façon canonique d'utiliser chaque API.

Astuces

Lisez ${CLAUDE_SKILL_DIR}/references/tldraw-releases.txt pour le changelog filtré — c'est la source primaire de ce qui a changé
Cherchez dans ${CLAUDE_SKILL_DIR}/references/tldraw-full-docs.txt quand vous avez besoin de docs sur une API spécifique
Quand cherchez les types tldraw, essayez plusieurs chemins — la structure du répertoire dist varie selon la version et le gestionnaire de paquets