HolyStitch

¿Qué es HolyStitch?

HolyStitch es una herramienta MCP (Model Context Protocol) que compila un proyecto de Google Stitch en una base de código Next.js funcional. En lugar de pedirle a un modelo que “adivine” la conversión, lee tu proyecto Stitch mediante la Stitch API y genera archivos de salida JSX/Next.js completos.

Su propósito principal es convertir pantallas de Stitch en un proyecto React/Next.js en disco de manera determinista, incluyendo estructura de componentes, configuración de estilos y HTML fuente preservado para referencia, para que puedas revisar el resultado y completar cualquier elemento pendiente de la lista de verificación.

Características clave

• Ingestión de Stitch API (por ID de proyecto): Obtiene todas las pantallas de tu proyecto Stitch usando la Stitch API, con un ID de proyecto Stitch que proporcionas.
• Compilación estructurada en React (sin prompts): Analiza componentes basados en marcadores HTML incrustados en Stitch (p. ej., <!-- ComponentName -->) y escribe JSX React válido.
• Salida determinista de proyecto Next.js: Produce un directorio de proyecto Next.js con app/, components/ y archivos de soporte, listo para instalar y ejecutar.
• Extracción y desduplicación de componentes compartidos: Detecta componentes compartidos entre múltiples pantallas y los escribe una sola vez en components/ en lugar de duplicarlos por página.
• Extracción de tema Tailwind: Extrae la configuración exacta del tema Tailwind, incluyendo colores, fuentes y ajustes de modo oscuro, y la escribe en tailwind.config.js.
• Manejo de casos límite JSX/HTML: Realiza conversiones comunes seguras para JSX y normalización, incluyendo class→className, for→htmlFor, conversión de cadenas de estilo inline en objetos style (incluyendo url(), calc(), var() y font-variation-settings), renderizado correcto de fuentes de iconos (p. ej., Material Symbols/Icons), bloques de código escapados dentro de <pre><code> y manejo de atributos duplicados.

Cómo usar HolyStitch

1. Construye la herramienta localmente
   • Clona y construye:
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Anota la ruta completa a la carpeta compilada (p. ej., /Users/alice/holystitch).
2. Obtén una clave de Stitch API
   • Copia tu clave API desde la configuración de tu proyecto Stitch.
3. Configura tu host MCP (Claude Desktop / Cursor / Windsurf / otros hosts MCP)
   • Apunta el host MCP al paquete compilado (usando la ruta dist/index.js compilada) y establece STITCH_API_KEY.
   • Ejemplo para Claude Desktop:
     • Agrega una entrada a claude_desktop_config.json con command: "node", args: ["<ruta completa>/dist/index.js"] y env: { "STITCH_API_KEY": "tu-clave-api-aqui" }.
4. Proporciona tu ID de proyecto Stitch
   • Usa el ID de proyecto de la URL de Stitch (la documentación del repositorio lo muestra como parte de https://stitch.withgoogle.com/project/<projectId>).
5. Ejecuta la conversión
   • Pídele a tu asistente de IA (conectado al servidor MCP) que convierta el ID de proyecto Stitch en una app Next.js en la carpeta de destino.
   • La herramienta escribe los archivos del proyecto en disco; la IA puede ayudar luego con elementos pendientes de la lista de verificación (como enrutamiento, fuentes o cualquier caso límite JSX restante) que requieran revisión humana.

Casos de uso

• Convierte páginas de aterrizaje Stitch existentes en una app Next.js: Compila pantallas Stitch en componentes React y rutas app/ para que el diseño se convierta en código ejecutable.
• Maneja proyectos Stitch grandes con múltiples pantallas y UI compartida: Usa desduplicación de componentes para extraer secciones repetidas (p. ej., barras de navegación, pies de página, secciones hero) en componentes compartidos.
• Preserva la configuración de estilos exactamente: Extrae el mismo tema Tailwind (colores, fuentes y config de modo oscuro) en tailwind.config.js en lugar de recrear estilos manualmente.
• Reduce el “adivinado” de LLM en conversiones HTML a JSX: Confía en las reglas específicas de seguridad JSX del compilador (renombrado de atributos, análisis de estilos inline, bloques de código escapados) para evitar fallos comunes de conversión.
• Genera una base de código revisada para desarrollo iterativo: Comienza con un proyecto Next.js generado (con stitch-source/ preservado para referencia) y luego ajusta funcionalidad y enrutamiento con tu flujo de trabajo de desarrollo propio.

Preguntas frecuentes

• ¿HolyStitch usa tokens de IA para convertir mi proyecto Stitch? La descripción del repositorio indica que es “compilado, no promptado” y afirma “cero tokens” para la conversión en sí.

• ¿Qué necesito proporcionar para ejecutar una conversión? Proporcionas un ID de proyecto Stitch y estableces STITCH_API_KEY en la configuración de tu host MCP.

• ¿Qué framework genera? La salida predeterminada documentada es un proyecto Next.js. La herramienta también menciona una opción para usar vite como framework, aunque Next.js es el enfoque principal en los ejemplos de salida.

• ¿Qué termina en la carpeta generada? La salida de ejemplo incluye components/, app/, stitch-source/ (HTML original conservado para referencia), tailwind.config.js y archivos de configuración del proyecto como package.json y tsconfig.json.

• ¿Puede convertir solo ciertas pantallas? Las opciones documentadas incluyen un ajuste screenIds que se puede usar para pasar IDs de pantallas específicas y convertir un subconjunto; el predeterminado es “todas las pantallas”.

Alternativas

• Conversión manual de Stitch a React: Reconstruye componentes y estilos Tailwind a mano. Puede funcionar para proyectos pequeños, pero suele tomar más tiempo y ser más propenso a errores en casos límite de atributos JSX.
• Conversión de HTML a React/Next.js basada en prompts con un asistente de IA: Envía el HTML/markup exportado a un LLM para transformarlo. A diferencia de un enfoque de compilador, puede requerir más iteraciones para corregir problemas de className/atributos y estructuras duplicadas.
• Generadores de plantillas genéricos para diseño a código: Usa herramientas que generan código React/Next.js a partir de activos de diseño. Estas pueden no preservar la estructura específica de componentes de Stitch, detalles del tema Tailwind o marcadores incrustados como lo hace un compilador consciente de Stitch.
• Reimplementación de UI centrada en componentes: Trata cada pantalla como una tarea de implementación separada en React y construye componentes compartidos tú mismo. Esto da máximo control, pero traslada todo el trabajo de conversión al desarrollo en lugar de la generación.