HolyStitch

Что такое holystitch?

HolyStitch — это инструмент MCP (Model Context Protocol), который компилирует проект Google Stitch в рабочий Next.js-код. Вместо того чтобы просить модель «угадывать» конвертацию, он читает ваш проект Stitch через Stitch API и генерирует полные файлы JSX/Next.js.

Его основная цель — превратить экраны Stitch в React/Next.js-проект на диске детерминированным способом, включая структуру компонентов, настройку стилей и сохранённый исходный HTML для справки — чтобы вы могли проверить результат и завершить оставшиеся пункты чек-листа.

Ключевые возможности

• Интеграция с Stitch API (по ID проекта): Загружает каждый экран из вашего проекта Stitch с помощью Stitch API, используя предоставленный ID проекта Stitch.
• Структурированная компиляция в React (без промптинга): Парсит компоненты на основе HTML-маркеров в Stitch (например, <!-- ComponentName -->) и пишет валидный React JSX.
• Детерминированный вывод Next.js-проекта: Создаёт директорию Next.js-проекта с app/, components/ и вспомогательными файлами, готовыми к установке и запуску.
• Извлечение и дедупликация общих компонентов: Обнаруживает компоненты, общие для нескольких экранов, и записывает их один раз в components/, вместо дублирования на страницу.
• Извлечение темы Tailwind: Вытаскивает точную конфигурацию темы Tailwind, включая цвета, шрифты и настройки тёмного режима, и записывает в tailwind.config.js.
• Обработка граничных случаев JSX/HTML: Выполняет распространённые безопасные для JSX конверсии и нормализацию, включая class→className, for→htmlFor, преобразование строк inline-стилей в объекты стилей (включая url(), calc(), var() и font-variation-settings), корректный рендеринг иконочных шрифтов (например, Material Symbols/Icons), экранированные блоки кода внутри <pre><code> и обработку дублирующихся атрибутов.

Как использовать holystitch

1. Собрать инструмент локально
   • Клонировать и собрать:
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Запомнить полный путь к собранной папке (например, /Users/alice/holystitch).
2. Получить ключ Stitch API
   • Скопировать API-ключ из настроек вашего проекта Stitch.
3. Настроить MCP-хост (Claude Desktop / Cursor / Windsurf / другие MCP-хосты)
   • Указать MCP-хосту путь к собранному пакету (используя путь к dist/index.js) и установить STITCH_API_KEY.
   • Пример для Claude Desktop:
     • Добавить запись в claude_desktop_config.json с command: "node", args: ["<full path>/dist/index.js"] и env: { "STITCH_API_KEY": "your-api-key-here" }.
4. Предоставить ID проекта Stitch
   • Использовать ID проекта из URL Stitch (документация репозитория показывает его как часть https://stitch.withgoogle.com/project/<projectId>).
5. Запустить конвертацию
   • Попросить вашего ИИ-ассистента (подключённого к MCP-серверу) конвертировать ID проекта Stitch в Next.js-приложение в целевую папку.
   • Инструмент запишет файлы проекта на диск; ИИ затем поможет с последующими пунктами чек-листа (например, роутинг, шрифты или оставшиеся граничные случаи JSX), требующими проверки человеком.

Сценарии использования

• Конвертировать существующие лендинги Stitch в Next.js-приложение: Скомпилировать экраны Stitch в React-компоненты и маршруты app/, чтобы дизайн стал рабочим кодом.
• Обработать большие проекты Stitch с несколькими экранами и общим UI: Использовать дедупликацию компонентов для извлечения повторяющихся секций (например, навбары, футеры, hero-секции) в общие компоненты.
• Сохранить конфигурацию стилей точно: Извлечь ту же тему Tailwind (цвета, шрифты и конфиг тёмного режима) в tailwind.config.js, вместо ручного воссоздания стилей.
• Сократить угадывания LLM при конвертации HTML-to-JSX: Полагаться на конкретные правила безопасности JSX компилятора (переименование атрибутов, парсинг inline-стилей, экранированные блоки кода), чтобы избежать типичных ошибок конвертации.
• Сгенерировать проверяемый кодбейс для итеративной разработки: Начать с сгенерированного Next.js-проекта (с сохранённым stitch-source/ для справки), а затем доработать функциональность и роутинг в своём workflow разработки.

FAQ

• Использует ли holystitch AI-токены для конвертации моего проекта Stitch? Описание репозитория гласит, что это «compiled, not prompted» и заявляет о «zero tokens» для самой конвертации.

• Что нужно предоставить для запуска конвертации? Вы предоставляете ID проекта Stitch и устанавливаете STITCH_API_KEY в конфигурации MCP-хоста.

• Какой фреймворк он генерирует? Документированный вывод по умолчанию — проект Next.js. Инструмент также упоминает опцию использования vite как фреймворка, хотя Next.js — основной фокус в примерах вывода.

• Что оказывается в сгенерированной папке? Пример вывода включает components/, app/, stitch-source/ (исходный HTML сохранён для справки), tailwind.config.js и файлы конфигурации проекта вроде package.json и tsconfig.json.

• Может ли он конвертировать только определённые экраны? Документированные опции включают настройку screenIds, которую можно использовать для передачи конкретных ID экранов и конвертации подмножества; по умолчанию — «все экраны».

Альтернативы

• Ручная конвертация Stitch в React: Перестраивать компоненты и стили Tailwind вручную. Подходит для небольших проектов, но обычно занимает больше времени и склонна к ошибкам в краевых случаях JSX-атрибутов.
• Конвертация HTML в React/Next.js на основе промптов с ИИ-помощником: Отправлять экспортированный HTML/разметку в LLM для преобразования. В отличие от компилятора, может потребовать больше итераций для исправления проблем с className/атрибутами и дублированными структурами.
• Универсальные генераторы шаблонов для design-to-code: Использовать инструменты, которые создают React/Next.js код из дизайн-активов. Они могут не сохранить структуру компонентов, специфичную для Stitch, детали темы Tailwind или встроенные маркеры, как это делает компилятор, заточенный под Stitch.
• Пере実ализация UI с приоритетом на компоненты: Рассматривать каждый экран как отдельную задачу реализации в React и строить общие компоненты самостоятельно. Это даёт максимальный контроль, но переносит всю работу по конвертации на разработку вместо генерации.