HolyStitch

O que é HolyStitch?

HolyStitch é uma ferramenta MCP (Model Context Protocol) que compila um projeto Google Stitch em um código Next.js funcional. Em vez de pedir a um modelo para “adivinhar” uma conversão, ela lê seu projeto Stitch via Stitch API e gera arquivos JSX/Next.js completos.

Seu propósito principal é transformar telas Stitch em um projeto React/Next.js no disco de forma determinística, incluindo estrutura de componentes, configuração de estilos e HTML original preservado para referência — para que você possa revisar o resultado e completar itens restantes da lista de verificação.

Principais Recursos

• Ingestão da Stitch API (por ID do projeto): Busca todas as telas do seu projeto Stitch usando a Stitch API, com um ID de projeto Stitch que você fornece.
• Compilação React estruturada (sem prompts): Analisa componentes com base em marcadores HTML incorporados no Stitch (ex.: <!-- ComponentName -->) e escreve JSX React válido.
• Saída determinística de projeto Next.js: Produz um diretório de projeto Next.js contendo app/, components/ e arquivos de suporte, pronto para instalar e executar.
• Extração e desduplicação de componentes compartilhados: Detecta componentes compartilhados entre várias telas e os escreve uma vez em components/ em vez de duplicá-los por página.
• Extração de tema Tailwind: Extrai a configuração exata do tema Tailwind, incluindo cores, fontes e configurações de modo escuro, e a escreve em tailwind.config.js.
• Tratamento de casos extremos JSX/HTML: Realiza conversões comuns seguras para JSX e normalização, incluindo class→className, for→htmlFor, conversão de strings de estilo inline em objetos de estilo (incluindo url(), calc(), var() e font-variation-settings), renderização correta de fontes de ícones (ex.: Material Symbols/Icons), blocos de código escapados dentro de <pre><code> e tratamento de atributos duplicados.

Como Usar HolyStitch

1. Construa a ferramenta localmente
   • Clone e construa:
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Anote o caminho completo da pasta construída (ex.: /Users/alice/holystitch).
2. Obtenha uma chave da Stitch API
   • Copie sua chave de API das configurações do projeto Stitch.
3. Configure seu host MCP (Claude Desktop / Cursor / Windsurf / outros hosts MCP)
   • Aponte o host MCP para o pacote construído (usando o caminho dist/index.js construído) e defina STITCH_API_KEY.
   • Exemplo para Claude Desktop:
     • Adicione uma entrada em claude_desktop_config.json com command: "node", args: ["<caminho-completo>/dist/index.js"] e env: { "STITCH_API_KEY": "sua-chave-api-aqui" }.
4. Forneça o ID do seu projeto Stitch
   • Use o ID do projeto da URL do Stitch (a documentação do repositório o mostra como parte de https://stitch.withgoogle.com/project/<projectId>).
5. Execute a conversão
   • Peça ao seu assistente de IA (conectado ao servidor MCP) para converter o ID do projeto Stitch em um app Next.js na pasta de destino.
   • A ferramenta escreve os arquivos do projeto no disco; a IA pode então ajudar com itens subsequentes da lista de verificação (como roteamento, fontes ou casos extremos JSX restantes) que exigem revisão humana.

Casos de Uso

• Converta landing pages existentes do Stitch em um app Next.js: Compile telas Stitch em componentes React e rotas app/ para que o design se torne código executável.
• Lide com projetos Stitch grandes de múltiplas telas com UI compartilhada: Use desduplicação de componentes para extrair seções repetidas (ex.: barras de navegação, rodapés, seções hero) em componentes compartilhados.
• Preserve configuração de estilos exatamente: Extraia o mesmo tema Tailwind (cores, fontes e config de modo escuro) em tailwind.config.js em vez de recriar estilos manualmente.
• Reduza adivinhações de LLM na conversão HTML-para-JSX: Confie nas regras específicas de segurança JSX do compilador (renomeação de atributos, análise de estilo inline, blocos de código escapados) para evitar falhas comuns de conversão.
• Gere um código revisado para desenvolvimento iterativo: Comece de um projeto Next.js gerado (com stitch-source/ preservado para referência) e ajuste funcionalidade e roteamento com seu fluxo de desenvolvimento próprio.

FAQ

• O HolyStitch usa tokens de IA para converter meu projeto Stitch? A descrição do repositório afirma que é “compilado, não promptado” e reivindica “zero tokens” para a conversão em si.

• O que preciso fornecer para executar uma conversão? Você fornece um ID de projeto Stitch e define STITCH_API_KEY na configuração do seu host MCP.

• Qual framework ele gera? A saída padrão documentada é um projeto Next.js. A ferramenta também menciona uma opção para usar vite como framework, embora Next.js seja o foco principal nos exemplos de saída.

• O que acaba na pasta gerada? A saída de exemplo inclui components/, app/, stitch-source/ (HTML original mantido para referência), tailwind.config.js e arquivos de configuração do projeto como package.json e tsconfig.json.

• Pode converter apenas certas telas? As opções documentadas incluem uma configuração screenIds que pode ser usada para passar IDs de telas específicas e converter um subconjunto; o padrão é “todas as telas.”

Alternativas

• Conversão manual Stitch-para-React: Reconstrua componentes e estilos Tailwind manualmente. Funciona para projetos pequenos, mas geralmente leva mais tempo e é mais propenso a erros em casos extremos de atributos JSX.
• Conversão HTML-para-React/Next.js baseada em prompts com um assistente de IA: Envie o HTML/markup exportado para um LLM para transformação. Diferente de uma abordagem de compilador, pode exigir mais iterações para corrigir problemas de className/atributos e estruturas duplicadas.
• Geradores de templates genéricos para design-para-código: Use ferramentas que geram código React/Next.js a partir de assets de design. Elas podem não preservar a estrutura de componentes específica do Stitch, detalhes do tema Tailwind ou marcadores incorporados como faz um compilador consciente do Stitch.
• Reimplementação de UI com foco em componentes: Trate cada tela como uma tarefa de implementação separada em React e construa componentes compartilhados manualmente. Isso dá controle máximo, mas transfere todo o trabalho de conversão para o desenvolvimento em vez da geração.