HolyStitch

Cos'è holystitch?

HolyStitch è uno strumento MCP (Model Context Protocol) che converte un progetto Google Stitch in un codebase Next.js funzionante. Invece di chiedere a un modello di “indovinare” la conversione, legge il tuo progetto Stitch tramite l'API Stitch e genera file di output JSX/Next.js completi.

Il suo scopo principale è trasformare le schermate Stitch in un progetto React/Next.js su disco in modo deterministico, inclusa la struttura dei componenti, la configurazione degli stili e l'HTML sorgente preservato per riferimento—così puoi rivedere il risultato e completare eventuali voci rimanenti della checklist.

Caratteristiche principali

• Ingestione API Stitch (per ID progetto): Recupera ogni schermata dal tuo progetto Stitch usando l'API Stitch, con un ID progetto Stitch che fornisci.
• Compilazione React strutturata (senza prompting): Analizza i componenti basandosi sui marker HTML incorporati in Stitch (es. <!-- ComponentName -->) e scrive JSX React valido.
• Output progetto Next.js deterministico: Produce una directory di progetto Next.js contenente app/, components/ e file di supporto, pronta per l'installazione e l'esecuzione.
• Estrazione e deduplicazione componenti condivisi: Rileva componenti condivisi tra più schermate e li scrive una sola volta in components/ invece di duplicarli per pagina.
• Estrazione tema Tailwind: Estrae la configurazione esatta del tema Tailwind, inclusi colori, font e impostazioni dark mode, e la scrive in tailwind.config.js.
• Gestione edge-case JSX/HTML: Esegue conversioni comuni sicure per JSX e normalizzazioni, inclusi class→className, for→htmlFor, conversione di stringhe stile inline in oggetti style (inclusi url(), calc(), var() e font-variation-settings), rendering corretto font icone (es. Material Symbols/Icons), blocchi codice escaped in <pre><code> e gestione attributi duplicati.

Come usare holystitch

1. Compila lo strumento localmente
   • Clona e compila:
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Nota il percorso completo della cartella compilata (es. /Users/alice/holystitch).
2. Ottieni una chiave API Stitch
   • Copia la tua chiave API dalle impostazioni del progetto Stitch.
3. Configura il tuo host MCP (Claude Desktop / Cursor / Windsurf / altri host MCP)
   • Punta l'host MCP al pacchetto compilato (usando il percorso dist/index.js compilato) e imposta STITCH_API_KEY.
   • Esempio per Claude Desktop:
     • Aggiungi una voce a claude_desktop_config.json con command: "node", args: ["<percorso completo>/dist/index.js"] e env: { "STITCH_API_KEY": "la-tua-api-key-qui" }.
4. Fornisci l'ID del tuo progetto Stitch
   • Usa l'ID progetto dall'URL Stitch (la documentazione del repo lo mostra come parte di https://stitch.withgoogle.com/project/<projectId>).
5. Esegui la conversione
   • Chiedi al tuo assistente AI (connesso al server MCP) di convertire l'ID progetto Stitch in un'app Next.js nella cartella di destinazione.
   • Lo strumento scrive i file del progetto su disco; l'AI può poi aiutare con voci successive della checklist (come routing, font o edge-case JSX rimanenti) che richiedono revisione umana.

Casi d'uso

• Converti landing page Stitch esistenti in un'app Next.js: Compila schermate Stitch in componenti React e route app/ così il design diventa codice eseguibile.
• Gestisci grandi progetti Stitch multi-schermata con UI condivisa: Usa la deduplicazione componenti per estrarre sezioni ripetute (es. barre nav, footer, sezioni hero) in componenti condivisi.
• Preserva esattamente la configurazione stili: Estrae lo stesso tema Tailwind (colori, font e config dark mode) in tailwind.config.js invece di ricreare gli stili manualmente.
• Riduci il guesswork LLM nella conversione HTML-to-JSX: Affidati alle regole specifiche di sicurezza JSX del compilatore (rinomini attributi, parsing stile inline, blocchi codice escaped) per evitare fallimenti comuni di conversione.
• Genera un codebase rivisto per sviluppo iterativo: Parti da un progetto Next.js generato (con stitch-source/ preservato per riferimento) e poi adatta funzionalità e routing con il tuo workflow di sviluppo.

FAQ

• holystitch usa token AI per convertire il mio progetto Stitch? La descrizione del repository afferma che è “compilato, non promptato” e dichiara “zero token” per la conversione stessa.

• Cosa devo fornire per eseguire una conversione? Fornisci un ID progetto Stitch e imposta STITCH_API_KEY nella configurazione del tuo host MCP.

• Che framework genera? L'output predefinito documentato è un progetto Next.js. Lo strumento menziona anche un'opzione per usare vite come framework, anche se Next.js è il focus principale negli esempi di output.

• Cosa finisce nella cartella generata? L'esempio di output include components/, app/, stitch-source/ (HTML originale conservato per riferimento), tailwind.config.js e file di configurazione progetto come package.json e tsconfig.json.

• Può convertire solo certe schermate? Le opzioni documentate includono un'impostazione screenIds che può essere usata per passare ID schermate specifici e convertire un sottoinsieme; il default è “tutte le schermate.”

Alternative

• Conversion manuale da Stitch a React: Ricostruire componenti e stili Tailwind a mano. Funziona per progetti piccoli ma richiede tipicamente più tempo ed è più soggetto a errori per i casi limite degli attributi JSX.
• Conversione HTML-to-React/Next.js basata su prompt con un assistente AI: Inviare l'HTML/markup esportato a un LLM per la trasformazione. A differenza di un approccio compilatore, potrebbe richiedere più iterazioni per correggere problemi di className/attributi e strutture duplicate.
• Generatori di template generici per design-to-code: Usare tool che generano codice React/Next.js da asset di design. Questi potrebbero non preservare la struttura componenti specifica di Stitch, dettagli del tema Tailwind o marker incorporati come fa un compilatore consapevole di Stitch.
• Riimplementazione UI component-first: Trattare ogni schermata come un compito di implementazione separato in React e creare componenti condivisi manualmente. Offre il massimo controllo ma sposta tutto il lavoro di conversione sullo sviluppo anziché sulla generazione.