HolyStitch

Qu'est-ce que holystitch ?

HolyStitch est un outil MCP (Model Context Protocol) qui compile un projet Google Stitch en base de code Next.js fonctionnelle. Au lieu de demander à un modèle de « deviner » une conversion, il lit votre projet Stitch via l’API Stitch et génère des fichiers JSX/Next.js complets.

Son objectif principal est de transformer les écrans Stitch en projet React/Next.js sur disque de manière déterministe, incluant la structure des composants, la configuration de style, et le HTML source préservé pour référence — afin que vous puissiez vérifier le résultat et compléter les éléments restants de la checklist.

Fonctionnalités clés

• Ingestion via l’API Stitch (par ID de projet) : Récupère tous les écrans de votre projet Stitch via l’API Stitch, en utilisant un ID de projet Stitch fourni.
• Compilation React structurée (sans prompting) : Analyse les composants basés sur les marqueurs HTML intégrés dans Stitch (ex. <!-- ComponentName -->) et écrit du JSX React valide.
• Sortie de projet Next.js déterministe : Produit un répertoire de projet Next.js contenant app/, components/, et fichiers de support, prêt à installer et exécuter.
• Extraction et déduplication de composants partagés : Détecte les composants partagés entre plusieurs écrans et les écrit une seule fois dans components/ au lieu de les dupliquer par page.
• Extraction du thème Tailwind : Extrait la configuration exacte du thème Tailwind, incluant couleurs, polices et paramètres de mode sombre, et l’écrit dans tailwind.config.js.
• Gestion des cas limites JSX/HTML : Effectue des conversions et normalisations JSX sécurisées courantes, incluant class→className, for→htmlFor, conversion des chaînes de style inline en objets style (incluant url(), calc(), var(), et font-variation-settings), rendu correct des polices d’icônes (ex. Material Symbols/Icons), blocs de code échappés dans <pre><code>, et gestion des attributs dupliqués.

Comment utiliser holystitch

1. Construire l’outil localement
   • Cloner et construire :
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Noter le chemin complet vers le dossier construit (ex. /Users/alice/holystitch).
2. Obtenir une clé API Stitch
   • Copier votre clé API depuis les paramètres de votre projet Stitch.
3. Configurer votre hôte MCP (Claude Desktop / Cursor / Windsurf / autres hôtes MCP)
   • Pointer l’hôte MCP vers le package construit (en utilisant le chemin dist/index.js construit) et définir STITCH_API_KEY.
   • Exemple pour Claude Desktop :
     • Ajouter une entrée à claude_desktop_config.json avec command: "node", args: ["<chemin complet>/dist/index.js"], et env: { "STITCH_API_KEY": "votre-clé-api-ici" }.
4. Fournir votre ID de projet Stitch
   • Utiliser l’ID de projet depuis l’URL Stitch (la documentation du repo l’indique comme partie de https://stitch.withgoogle.com/project/<projectId>).
5. Lancer la conversion
   • Demander à votre assistant IA (connecté au serveur MCP) de convertir l’ID de projet Stitch en app Next.js dans le dossier de destination.
   • L’outil écrit les fichiers du projet sur disque ; l’IA peut ensuite aider avec les éléments de suivi de la checklist (comme le routage, les polices, ou tout cas limite JSX restant) nécessitant une revue humaine.

Cas d’usage

• Convertir des landing pages Stitch existantes en app Next.js : Compiler les écrans Stitch en composants React et routes app/ pour rendre le design en code exécutable.
• Gérer de grands projets Stitch multi-écrans avec UI partagée : Utiliser la déduplication de composants pour extraire les sections répétées (ex. barres de navigation, pieds de page, sections hero) en composants partagés.
• Préserver la configuration de style exactement : Extraire le même thème Tailwind (couleurs, polices, config mode sombre) dans tailwind.config.js plutôt que de recréer les styles manuellement.
• Réduire les approximations LLM dans la conversion HTML-to-JSX : S’appuyer sur les règles spécifiques de sécurité JSX du compilateur (renommage d’attributs, parsing de style inline, blocs de code échappés) pour éviter les échecs courants de conversion.
• Générer une base de code à reviewer pour développement itératif : Partir d’un projet Next.js généré (avec stitch-source/ préservé pour référence) puis ajuster fonctionnalité et routage avec votre workflow de développement.

FAQ

• holystitch utilise-t-il des tokens IA pour convertir mon projet Stitch ? La description du repo indique qu’il s’agit de « compilation, pas de prompting » et revendique « zéro token » pour la conversion elle-même.

• Que dois-je fournir pour lancer une conversion ? Vous fournissez un ID de projet Stitch et définissez STITCH_API_KEY dans la configuration de votre hôte MCP.

• Quel framework génère-t-il ? La sortie par défaut documentée est un projet Next.js. L’outil mentionne aussi une option pour utiliser vite comme framework, bien que Next.js soit le focus principal dans les exemples de sortie.

• Que contient le dossier généré ? L’exemple de sortie inclut components/, app/, stitch-source/ (HTML original conservé pour référence), tailwind.config.js, et fichiers de configuration de projet comme package.json et tsconfig.json.

• Peut-il convertir seulement certains écrans ? Les options documentées incluent un paramètre screenIds pour passer des ID d’écrans spécifiques et convertir un sous-ensemble ; par défaut, c’est « tous les écrans ».

Alternatives

• Conversion manuelle Stitch vers React : Reconstruire les composants et styles Tailwind à la main. Cela peut convenir aux petits projets mais prend généralement plus de temps et est plus sujet aux erreurs pour les cas limites des attributs JSX.
• Conversion HTML vers React/Next.js basée sur des prompts avec un assistant IA : Envoyer le HTML/export markup à un LLM pour transformation. Contrairement à une approche compilateur, cela peut nécessiter plus d’itérations pour corriger les problèmes de className/attributs et structures dupliquées.
• Générateurs de templates génériques design-to-code : Utiliser des outils qui génèrent du code React/Next.js à partir d’actifs de design. Ils ne préservent pas forcément la structure de composants spécifique à Stitch, les détails du thème Tailwind ou les marqueurs intégrés comme le fait un compilateur conscient de Stitch.
• Réimplémentation UI component-first : Traiter chaque écran comme une tâche d’implémentation séparée en React et créer soi-même les composants partagés. Cela offre un contrôle maximal mais reporte entièrement le travail de conversion vers le développement plutôt que la génération.