Utilisation de Cursor Canvas pour la planification visuelle de projets

Cursor Canvas est une surface de planification visuelle qui vit dans votre IDE. Il vous permet de dessiner des diagrammes d'architecture, de cartographier les flux de fonctionnalités, de planifier les tâches de sprint et de partager un contexte visuel avec votre équipe, tout sans quitter Cursor. Contrairement à un tableau blanc statique, Canvas s'intègre à votre codebase, vous permettant de lier des diagrammes à des fichiers, des fonctions et des modèles de données réels. Ce guide couvre tout, de la création de votre premier canevas à sa publication et au dépannage de la fameuse erreur « Canvas file not found ».

Qu'est-ce que Cursor Canvas ?

Canvas est un espace de travail visuel où vous pouvez :

• Dessiner des diagrammes d'architecture avec des boîtes, des flèches et des annotations
• Lier des artefacts de code en faisant glisser des fichiers, des fonctions ou des classes sur le canevas
• Planifier des fonctionnalités visuellement avant d'écrire du code
• Partager avec votre équipe en publiant des canevas sous forme de liens autonomes
• Annoter des décisions avec des notes, des TODO et des justifications de conception

La différence clé avec des outils externes comme Miro ou Figma est que Canvas est sensible au contexte. Lorsque vous placez un composant sur le canevas, il connaît le chemin du fichier réel, les exports et les dépendances de ce composant.

Prérequis

• Cursor version 0.42 ou plus récente (Canvas a été introduit fin 2024)
• Un dossier de projet ouvert dans Cursor (Canvas fonctionne dans un contexte de projet)
• Compte Cursor pour les fonctionnalités de publication (le niveau gratuit suffit)

Création de votre premier canevas

Étape 1 : Ouvrir l'éditeur Canvas

Il y a trois façons d'ouvrir un nouveau canevas :

1. Palette de commandes : Cmd/Ctrl + Shift + P et tapez Canvas: New Canvas
2. Barre latérale : Cliquez sur l'icône Canvas dans la barre d'activité (barre latérale gauche)
3. Raccourci clavier : Cmd/Ctrl + Shift + C (configurable dans les paramètres)

Étape 2 : Ajouter des éléments au canevas

Commencez avec un canevas vide. Vous pouvez ajouter les types d'éléments suivants :

Élément	Comment l'ajouter	Objectif
Nœud de fichier	Faites glisser un fichier depuis l'explorateur	Affiche le fichier et ses relations
Nœud de fonction	Clic droit sur une fonction > "Add to Canvas"	Visualiser les graphes d'appels de fonction
Zone de texte	Double-clic sur un espace vide du canevas	Ajouter des notes, des étiquettes ou des décisions
Forme	Cliquez sur l'outil de forme dans la barre d'outils	Dessiner des boîtes, des cercles, des flèches
Image	Faites glisser un fichier image ou collez depuis le presse-papiers	Inclure des captures d'écran ou des maquettes

Étape 3 : Connecter les éléments

Dessinez des flèches entre les éléments pour montrer les relations :

1. Survolez un élément jusqu'à ce que des points de connexion apparaissent
2. Cliquez et faites glisser depuis un point de connexion vers un autre élément
3. Relâchez pour créer une connexion
4. Étiquetez facultativement la connexion (par ex. "imports", "calls", "extends")

Étape 4 : Enregistrer le canevas

Les canevas sont enregistrés sous forme de fichiers .canvas dans votre projet :

my-project/
  .cursor/
    canvases/
      architecture-overview.canvas
      feature-auth-flow.canvas
      sprint-planning.canvas

astuce

Nommez vos canevas de manière descriptive. Les fichiers Canvas sont versionnables, votre équipe peut donc suivre l'évolution des diagrammes dans le temps. Ajoutez un dossier canvases/ à votre dépôt et commettez-les avec votre code.

Publication de Canvas

La publication d'un canevas génère un lien partageable que n'importe qui peut consulter dans un navigateur, même sans Cursor installé. C'est utile pour partager des décisions d'architecture avec les parties prenantes ou l'intégration de nouveaux membres de l'équipe.

Comment publier

1. Ouvrez le canevas que vous souhaitez publier
2. Cliquez sur le bouton Publish dans la barre d'outils en haut à droite
3. Choisissez la visibilité :
   • Private - Seules les personnes avec le lien et un compte Cursor peuvent consulter
   • Unlisted - Toute personne avec le lien peut consulter (aucun compte requis)
   • Public - Découvrable et consultable par tous
4. Cliquez sur Publish
5. Copiez l'URL générée et partagez-la

Comment fonctionne la publication en interne

Lorsque vous publiez un canevas, Cursor :

1. Sérialise le canevas dans un format portable
2. Le télécharge dans le stockage cloud de Cursor
3. Génère une clé de projet unique pour la version publiée
4. Renvoie une URL contenant cette clé

attention

Les canevas publiés sont des instantanés à un moment donné. Si vous mettez à jour le canevas après la publication, la version publiée ne se met pas à jour automatiquement. Vous devez republier pour partager la dernière version. C'est par conception, pour empêcher les parties prenantes de voir des éditions à moitié terminées.

Gestion des clés de projet

Chaque canevas, qu'il soit local ou publié, est associé à une clé de projet. Comprendre le fonctionnement des clés de projet est essentiel pour le dépannage des problèmes de publication.

Qu'est-ce qu'une clé de projet ?

Une clé de projet est un identifiant unique qui lie un canevas à son contexte de projet. Elle permet au canevas publié de référencer la bonne structure de code, les chemins de fichiers et les métadonnées.

Le problème de la clé de projet temporaire par lancement

Les utilisateurs du forum signalent fréquemment que la publication de canevas échoue avec « Canvas file not found ». La cause première est que Cursor génère une clé de projet temporaire à chaque lancement lorsqu'il ne peut pas en trouver une persistante.

Voici ce qui se passe :

1. Vous ouvrez Cursor, et il attribue une clé de projet temporaire comme tmp_abc123
2. Vous créez et travaillez sur un canevas, qui est associé à tmp_abc123
3. Vous cliquez sur Publier
4. Le point de terminaison de publication recherche le canevas par la clé de projet actuelle
5. Si la clé a changé (parce que Cursor a été redémarré), la recherche échoue
6. Vous voyez « Canvas file not found »

Correction du problème de clé de projet

Solution 1 : Créer une clé de projet persistante

Ajoutez un fichier .cursor/project.json à la racine de votre projet :

{
  "projectKey": "persistent-key-my-project-2024",
  "projectName": "My Project",
  "createdAt": "2024-01-15T10:00:00Z"
}

Cela garantit que la clé de projet reste stable entre les redémarrages de Cursor.

astuce

Utilisez une clé de projet descriptive et unique. N'utilisez pas de valeurs génériques comme project1 ou test. Si deux projets sur votre machine ont la même clé, les recherches de canevas peuvent entrer en collision, et la publication échouera par intermittence.

Solution 2 : Réassocier le canevas

Si vous avez déjà un canevas avec une clé temporaire périmée :

1. Fermez le canevas dans Cursor
2. Ouvrez le fichier .canvas dans un éditeur de texte
3. Trouvez le champ projectKey
4. Mettez-le à jour pour correspondre à votre clé persistante
5. Enregistrez et rouvrez dans Cursor
6. Essayez de publier à nouveau

Le fichier .canvas est basé sur JSON, et la section pertinente ressemble à :

{
  "version": "1.0",
  "projectKey": "tmp_abc123",
  "elements": [...],
  "connections": [...]
}

Changez tmp_abc123 par votre clé persistante.

Solution 3 : Vider le cache de Canvas

Si les solutions ci-dessus ne fonctionnent pas, le cache local de Canvas peut être corrompu :

1. Fermez Cursor
2. Naviguez vers le répertoire de cache de Cursor :
   • macOS : ~/Library/Application Support/Cursor/canvas-cache/
   • Windows : %APPDATA%/Cursor/canvas-cache/
   • Linux : ~/.config/Cursor/canvas-cache/
3. Supprimez le contenu du dossier canvas-cache
4. Rouvrez Cursor
5. Rouvrez votre fichier canevas
6. Essayez de publier à nouveau

attention

Vider le cache de Canvas ne supprimera pas vos fichiers .canvas (ils se trouvent dans votre projet). Il supprime uniquement les tables de recherche temporaires qui mappent les clés de projet aux métadonnées de canevas. Le contenu réel de votre canevas est préservé.

Canvas autonome vs Glass App

Canvas est disponible dans deux contextes au sein de l'écosystème Cursor, et il y a des différences importantes.

Canvas autonome (Cursor IDE)

C'est le canevas auquel vous accédez depuis l'éditeur Cursor :

• Se trouve dans votre répertoire .cursor/canvases/
• Directement lié à votre projet ouvert
• Peut faire glisser des fichiers depuis l'explorateur vers le canevas
• Utilise la clé de projet de .cursor/project.json
• Idéal pour : diagrammes destinés aux développeurs, planification d'architecture, cartographie de code

Canvas Glass App

Glass est l'application visuelle autonome de Cursor (séparée de l'IDE). Canvas dans Glass :

• Se trouve dans le stockage propre de Glass, pas dans votre répertoire de projet
• Peut être lié à un projet mais fonctionne indépendamment
• A un espace de noms de clé de projet différent
• Prend en charge des éléments visuels plus riches (animations, composants interactifs)
• Idéal pour : présentations, démos pour les parties prenantes, partage entre équipes

Différences clés

Fonctionnalité	Canvas autonome	Canvas Glass App
Emplacement de stockage	.cursor/canvases/	Stockage cloud Glass
Source de la clé de projet	.cursor/project.json	Paramètres de projet Glass
Glisser-déposer de fichiers	Oui, depuis l'explorateur	Non, importation nécessaire
Collaboration en temps réel	Non	Oui
Portée de publication	Compte Cursor	Espace de travail Glass
Édition hors ligne	Oui	Non (connexion requise)

astuce

Si vous travaillez principalement dans l'IDE Cursor, utilisez le Canvas autonome pour la planification de développement. Utilisez le Canvas Glass App lorsque vous devez présenter à des parties prenantes non techniques ou collaborer en temps réel. Les deux ne sont pas interchangeables, et essayer d'utiliser Glass Canvas pour des tâches de cartographie de code sera frustrant car il ne peut pas référencer les fichiers en direct.

Migration entre autonome et Glass

Vous pouvez exporter un canevas autonome et l'importer dans Glass :

1. Ouvrez le canevas dans Cursor
2. Cliquez sur Export > Export as Glass-compatible
3. Enregistrez le fichier .glass-canvas
4. Ouvrez Glass
5. Cliquez sur Import et sélectionnez le fichier

Notez que les références de fichiers dans le canevas exporté seront converties en références statiques (elles ne se mettront pas à jour si le code sous-jacent change).

Conception de flux de travail visuel

Canvas n'est pas seulement pour les diagrammes d'architecture. C'est un espace de travail visuel polyvalent. Voici des modèles de flux de travail courants.

Flux de planification de fonctionnalité

1. Créez un canevas nommé feature-[name]-plan.canvas
2. Ajoutez des zones de texte pour les exigences de la fonctionnalité
3. Ajoutez des nœuds de fichier pour les fichiers qui seront modifiés
4. Dessinez des flèches montrant le flux de données
5. Ajoutez des zones de texte TODO pour les questions ouvertes
6. Partagez le canevas avec l'équipe avant l'implémentation
7. Utilisez le canevas comme référence pendant l'implémentation

Flux de revue de code

1. Créez un canevas pour le PR en cours de revue
2. Faites glisser les fichiers modifiés sur le canevas
3. Dessinez le graphe d'appels des fonctions modifiées
4. Annoté les problèmes potentiels avec des zones de texte rouges
5. Publiez le canevas et liez-le dans la description du PR

Flux d'intégration

1. Créez un fichier project-architecture.canvas
2. Ajoutez les points d'entrée principaux (par ex. index.ts, app.tsx)
3. Ajoutez les modules et services principaux
4. Dessinez le graphe de dépendances
5. Ajoutez des annotations expliquant la responsabilité de chaque module
6. Publiez comme lien non listé
7. Partagez avec les nouveaux membres de l'équipe dès leur premier jour

astuce

Gardez les canevas d'intégration à un niveau élevé. Un canevas avec 200 nœuds est plus difficile à comprendre que de lire le code directement. Visez 10-20 éléments qui montrent la vue d'ensemble, et laissez les nouvelles recrues explorer le code pour les détails.

Fonctionnalités avancées de Canvas

Connexions sensibles au code

Lorsque vous ajoutez une fonction ou une classe au canevas, Canvas peut détecter automatiquement ses dépendances et proposer de les ajouter :

1. Clic droit sur un nœud de fonction
2. Sélectionnez Show Dependencies
3. Canvas liste toutes les fonctions, modules et types que la fonction utilise
4. Cliquez sur n'importe quelle dépendance pour l'ajouter au canevas avec une connexion automatiquement dessinée

Modèles de Canvas

Créez des modèles de canevas réutilisables pour les types de diagrammes courants :

{
  "version": "1.0",
  "template": "microservice-architecture",
  "elements": [
    {"type": "text", "label": "API Gateway", "x": 400, "y": 50},
    {"type": "text", "label": "Auth Service", "x": 200, "y": 200},
    {"type": "text", "label": "User Service", "x": 600, "y": 200},
    {"type": "text", "label": "Database", "x": 400, "y": 350}
  ],
  "connections": [
    {"from": 0, "to": 1, "label": "routes to"},
    {"from": 0, "to": 2, "label": "routes to"},
    {"from": 1, "to": 3, "label": "reads/writes"},
    {"from": 2, "to": 3, "label": "reads/writes"}
  ]
}

Enregistrez-le comme .cursor/canvases/templates/microservice.canvas et utilisez Canvas: New from Template pour l'instancier.

Intégration de canevas dans la documentation

Vous pouvez intégrer des liens de canevas publiés dans votre documentation de projet :

## Architecture Overview

See our [visual architecture diagram](https://canvas.cursor.sh/c/persistent-key-my-project-2024/architecture-overview) for the full system map.

Key components:
- API Gateway handles routing
- Auth Service manages JWT verification
- User Service handles profile CRUD

Dépannage des problèmes courants

Problème : « Canvas file not found » lors de la publication

C'est l'erreur la plus courante. Suivez les étapes de dépannage de la clé de projet ci-dessus. Si elles ne résolvent pas le problème :

1. Vérifiez que le fichier .canvas existe sur le disque
2. Vérifiez que le fichier n'est pas ouvert dans une autre application (verrou de fichier)
3. Assurez-vous d'avoir les permissions d'écriture sur le répertoire .cursor/canvases/
4. Vérifiez votre connexion Internet (la publication nécessite un téléversement vers le cloud)

Problème : Les éléments du canevas disparaissent après le redémarrage

Cause : Le fichier canevas référence les éléments par des ID internes qui peuvent changer si la structure du code sous-jacent change (par ex. un fichier a été renommé ou supprimé).

Solution :

1. Ouvrez le canevas
2. Cliquez sur n'importe quel élément restant
3. Utilisez Reconnect to file pour le relier au chemin de fichier actuel
4. Réajoutez les éléments manquants

Problème : Le lien publié affiche une page blanche

Cause : La clé de projet dans l'URL publiée ne correspond à aucun canevas stocké.

Solution : Republiez le canevas après vous être assuré qu'une clé de projet persistante est définie. Les anciens liens des canevas à clé temporaire ne se résoudront pas.

Problème : Dégradation des performances de Canvas

Cause : Les grands canevas avec plus de 100 éléments peuvent ralentir le rendu.

Solution :

1. Divisez les grands canevas en plusieurs plus petits
2. Utilisez la fonctionnalité Collapse sur les groupes d'éléments
3. Supprimez les connexions inutilisées
4. Évitez d'ajouter des répertoires entiers comme nœuds uniques (utilisez des fichiers individuels à la place)

attention

N'ajoutez pas node_modules/ ou d'autres grands répertoires à un canevas. Chaque fichier devient un nœud séparé, et un répertoire avec 10 000 fichiers rendra Cursor inerte. Ajoutez toujours des fichiers ou des fonctions spécifiques, pas des dossiers entiers.

Bonnes pratiques

Garder les canevas focalisés

Un canevas doit répondre à une question. Au lieu d'un canevas « Tout en un », créez :

• data-flow.canvas - Comment les données circulent dans le système
• auth-architecture.canvas - Flux d'authentification et d'autorisation
• deployment-topology.canvas - Carte d'infrastructure et de déploiement
• sprint-3-plan.canvas - Plan visuel du sprint en cours

Contrôle de version de vos canevas

Les fichiers .canvas sont du JSON basé sur du texte. Commitez-les dans votre dépôt :

git add .cursor/canvases/
git commit -m "docs: update architecture canvas for new auth flow"

Cela vous donne un historique de l'évolution de votre architecture et permet aux membres de l'équipe de réviser les changements de diagrammes via les PR.

Hygiène régulière du canevas

À chaque sprint, revoyez vos canevas :

• Supprimez les diagrammes obsolètes
• Mettez à jour les architectures modifiées
• Supprimez les références aux fichiers supprimés
• Republiez ceux qui sont partagés en externe

Résumé

Cursor Canvas transforme la planification de projet d'une activité déconnectée en un flux de travail visuel intégré. L'erreur « Canvas file not found », le problème le plus courant auquel les utilisateurs sont confrontés, est enracinée dans le mécanisme de clé de projet temporaire par lancement et est entièrement résolue en créant une clé de projet persistante dans .cursor/project.json. Comprendre les différences entre les canevas autonomes et Glass App garantit que vous utilisez le bon outil pour chaque contexte, tandis que suivre les modèles de flux de travail visuel de ce guide rendra votre planification plus efficace et votre architecture plus communicable.