HolyStitch

Was ist holystitch?

HolyStitch ist ein MCP (Model Context Protocol) Tool, das ein Google Stitch-Projekt in eine lauffähige Next.js-Codebasis kompiliert. Statt ein Modell zu bitten, eine Konvertierung zu „erraten“, liest es Ihr Stitch-Projekt über die Stitch API und erzeugt vollständige JSX/Next.js-Ausgabedateien.

Sein Kernzweck ist es, Stitch-Screens deterministisch in ein React/Next.js-Projekt auf der Festplatte umzuwandeln – inklusive Komponentenstruktur, Styling-Setup und erhaltenem Quell-HTML zur Referenz –, damit Sie das Ergebnis prüfen und verbleibende Checklist-Items abschließen können.

Wichtige Funktionen

• Stitch-API-Ingestion (per Project-ID): Lädt jeden Screen aus Ihrem Stitch-Projekt über die Stitch API mit einer von Ihnen angegebenen Stitch-Project-ID.
• Strukturierte React-Kompilierung (ohne Prompting): Parst Komponenten basierend auf in Stitch eingebetteten HTML-Markern (z. B. <!-- ComponentName -->) und schreibt gültiges React JSX.
• Deterministische Next.js-Projekt-Ausgabe: Erzeugt ein Next.js-Projektverzeichnis mit app/, components/ und Support-Dateien, bereit zum Installieren und Ausführen.
• Extraktion und Deduplizierung geteilter Komponenten: Erkennt über mehrere Screens hinweg geteilte Komponenten und schreibt sie einmal in components/ statt sie pro Seite zu duplizieren.
• Tailwind-Theme-Extraktion: Extrahiert die exakte Tailwind-Theme-Konfiguration inklusive Farben, Schriftarten und Dark-Mode-Einstellungen und schreibt sie in tailwind.config.js.
• JSX/HTML-Edge-Case-Behandlung: Führt gängige JSX-sichere Konvertierungen und Normalisierungen durch, inklusive class→className, for→htmlFor, Umwandlung von Inline-Style-Strings in Style-Objekte (inkl. url(), calc(), var() und font-variation-settings), korrektes Icon-Font-Rendering (z. B. Material Symbols/Icons), escapte Code-Blöcke in <pre><code> und Behandlung doppelter Attribute.

So verwenden Sie holystitch

1. Tool lokal bauen
   • Klonen und bauen:
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Notieren Sie den vollständigen Pfad zum gebauten Ordner (z. B. /Users/alice/holystitch).
2. Stitch-API-Key besorgen
   • Kopieren Sie Ihren API-Key aus den Stitch-Projekt-Einstellungen.
3. MCP-Host konfigurieren (Claude Desktop / Cursor / Windsurf / andere MCP-Hosts)
   • Weisen Sie den MCP-Host auf das gebaute Paket (Pfad zu dist/index.js) hin und setzen Sie STITCH_API_KEY.
   • Beispiel für Claude Desktop:
     • Fügen Sie in claude_desktop_config.json einen Eintrag mit command: "node", args: ["<full path>/dist/index.js"] und env: { "STITCH_API_KEY": "your-api-key-here" } hinzu.
4. Stitch-Project-ID angeben
   • Verwenden Sie die Project-ID aus der Stitch-URL (Repo-Dokumentation zeigt sie als Teil von https://stitch.withgoogle.com/project/<projectId>).
5. Konvertierung ausführen
   • Bitten Sie Ihren AI-Assistenten (verbunden mit dem MCP-Server), die Stitch-Project-ID in eine Next.js-App im Zielordner umzuwandeln.
   • Das Tool schreibt die Projekt-Dateien auf die Festplatte; die AI kann dann bei Folge-Checklist-Items helfen (z. B. Routing, Fonts oder verbleibende JSX-Edge-Cases), die manuelle Überprüfung erfordern.

Anwendungsfälle

• Bestehende Stitch-Landing-Pages in eine Next.js-App umwandeln: Kompiliert Stitch-Screens in React-Komponenten und app/-Routen, damit das Design zu lauffähigem Code wird.
• Große Multi-Screen-Stitch-Projekte mit geteiltem UI handhaben: Nutzt Komponenten-Deduplizierung, um wiederholte Abschnitte (z. B. Navbars, Footers, Hero-Sections) in geteilte Komponenten zu extrahieren.
• Styling-Konfiguration exakt erhalten: Extrahiert dasselbe Tailwind-Theme (Farben, Fonts, Dark-Mode-Config) in tailwind.config.js statt Styles manuell neu zu erstellen.
• LLM-Raterei bei HTML-zu-JSX-Konvertierung reduzieren: Verlässt sich auf die spezifischen JSX-Sicherheitsregeln des Compilers (Attribut-Umbenennungen, Inline-Style-Parsing, escapte Code-Blöcke), um gängige Konvertierungsfehler zu vermeiden.
• Überprüfbare Codebasis für iterative Entwicklung generieren: Starten Sie von einem generierten Next.js-Projekt (mit erhaltenem stitch-source/ zur Referenz) und passen Sie dann Funktionalität und Routing in Ihrem eigenen Workflow an.

FAQ

• Verwendet holystitch AI-Tokens zur Konvertierung meines Stitch-Projekts? Die Repo-Beschreibung gibt an, es sei „compiled, not prompted“ und verspricht „zero tokens“ für die Konvertierung selbst.

• Was muss ich für eine Konvertierung angeben? Sie geben eine Stitch-Project-ID an und setzen STITCH_API_KEY in der MCP-Host-Konfiguration.

• Welches Framework erzeugt es? Die dokumentierte Standard-Ausgabe ist ein Next.js-Projekt. Das Tool erwähnt optional vite als Framework, wobei Next.js im Fokus der Ausgabebeispiele steht.

• Was landet im generierten Ordner? Das Ausgabebeispiel umfasst components/, app/, stitch-source/ (Original-HTML zur Referenz), tailwind.config.js sowie Projekt-Konfigurationsdateien wie package.json und tsconfig.json.

• Kann es nur bestimmte Screens konvertieren? Die dokumentierten Optionen beinhalten eine screenIds-Einstellung, um spezifische Screen-IDs für eine Teilmenge anzugeben; Standard ist „alle Screens“.

Alternativen

• Manuelle Stitch-to-React-Konvertierung: Components und Tailwind-Styles per Hand neu aufbauen. Funktioniert bei kleinen Projekten, dauert aber meist länger und ist fehleranfälliger bei JSX-Attribut-Kantenfällen.
• Prompt-basierte HTML-to-React/Next.js-Konvertierung mit KI-Assistenten: Exportiertes HTML/Markup an ein LLM schicken zur Umwandlung. Im Gegensatz zu einem Compiler-Ansatz erfordert es oft mehr Iterationen, um className-/Attribut-Probleme und Duplikate zu korrigieren.
• Generische Design-to-Code-Template-Generatoren: Tools nutzen, die React/Next.js-Code aus Design-Assets scaffolden. Diese bewahren Stitch-spezifische Component-Strukturen, Tailwind-Theme-Details oder eingebettete Marker oft nicht wie ein stitch-bewusster Compiler.
• Component-first UI-Neuinplementierung: Jede Screen als separate React-Implementierungsaufgabe behandeln und Shared Components selbst bauen. Bietet maximale Kontrolle, verlagert die Konvertierungsarbeit aber vollständig in die Entwicklung statt Generierung.