HolyStitch

holystitch란?

HolyStitch는 MCP (Model Context Protocol) 도구로, Google Stitch 프로젝트를 작동하는 Next.js 코드베이스로 컴파일합니다. 모델에게 변환을 “추측”하게 하는 대신 Stitch API를 통해 Stitch 프로젝트를 읽고 완전한 JSX/Next.js 출력 파일을 생성합니다.

핵심 목적은 Stitch 스크린을 디스크상의 React/Next.js 프로젝트로 결정론적으로 변환하는 것으로, 컴포넌트 구조, 스타일링 설정, 참조용 원본 HTML을 포함해 결과를 검토하고 남은 체크리스트 항목을 완료할 수 있습니다.

주요 기능

• Stitch API 수집 (프로젝트 ID 기준): 제공한 Stitch 프로젝트 ID를 사용해 Stitch API로 모든 스크린을 가져옵니다.
• 구조화된 React 컴파일 (프롬프트 아님): Stitch 내장 HTML 마커(예: <!-- ComponentName -->)를 기반으로 컴포넌트를 파싱해 유효한 React JSX를 작성합니다.
• 결정론적 Next.js 프로젝트 출력: app/, components/, 지원 파일이 포함된 Next.js 프로젝트 디렉터리를 생성해 설치 및 실행 준비 상태로 만듭니다.
• 공유 컴포넌트 추출 및 중복 제거: 여러 스크린에 공유된 컴포넌트를 감지해 페이지별 중복 대신 components/에 한 번만 작성합니다.
• Tailwind 테마 추출: 색상, 폰트, 다크 모드 설정을 포함한 정확한 Tailwind 테마 구성을 추출해 tailwind.config.js에 작성합니다.
• JSX/HTML 엣지 케이스 처리: 일반적인 JSX 안전 변환 및 정규화를 수행하며, class→className, for→htmlFor, 인라인 스타일 문자열을 스타일 객체로 변환(url(), calc(), var(), font-variation-settings 포함), 아이콘 폰트 렌더링(Materials 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 키 가져오기
   • Stitch 프로젝트 설정에서 API 키 복사.
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. Stitch 프로젝트 ID 제공
   • Stitch URL의 프로젝트 ID 사용(리포 문서에서 https://stitch.withgoogle.com/project/<projectId> 일부로 표시).
5. 변환 실행
   • MCP 서버에 연결된 AI 어시스턴트에게 Stitch 프로젝트 ID를 지정 폴더의 Next.js 앱으로 변환 요청.
   • 도구가 프로젝트 파일을 디스크에 작성; AI가 라우팅, 폰트, 남은 JSX 엣지 케이스 등 인간 검토가 필요한 후속 체크리스트를 도울 수 있습니다.

사용 사례

• 기존 Stitch 랜딩 페이지를 Next.js 앱으로 변환: Stitch 스크린을 React 컴포넌트와 app/ 라우트로 컴파일해 디자인을 실행 가능한 코드로 만듭니다.
• 공유 UI가 있는 대형 멀티 스크린 Stitch 프로젝트 처리: 컴포넌트 중복 제거를 사용해 반복 섹션(예: 네비게이션 바, 푸터, 히어로 섹션)을 공유 컴포넌트로 추출합니다.
• 스타일링 구성을 정확히 보존: Tailwind 테마(색상, 폰트, 다크 모드 설정)를 수동 재생성 대신 tailwind.config.js로 추출합니다.
• HTML-to-JSX 변환에서 LLM 추측 줄이기: 컴파일러의 특정 JSX 안전 규칙(속성 이름 변경, 인라인 스타일 파싱, 이스케이프 코드 블록)을 사용해 일반적인 변환 실패를 피합니다.
• 반복 개발을 위한 검토 코드베이스 생성: 생성된 Next.js 프로젝트(참조용 stitch-source/ 포함)에서 시작해 자체 개발 워크플로로 기능 및 라우팅 조정.

자주 묻는 질문

• holystitch가 Stitch 프로젝트 변환에 AI 토큰을 사용하나요? 리포지토리 설명에 “컴파일, 프롬프트 아님”이라고 명시하며 변환 자체에 “제로 토큰”이라고 주장합니다.

• 변환 실행에 무엇을 제공해야 하나요? Stitch 프로젝트 ID를 제공하고 MCP 호스트 구성에 STITCH_API_KEY를 설정합니다.

• 어떤 프레임워크를 생성하나요? 문서화된 기본 출력은 Next.js 프로젝트입니다. 도구는 vite 프레임워크 옵션도 언급하나, 출력 예시에서 Next.js가 주력입니다.

• 생성된 폴더에 무엇이 들어가나요? 예시 출력에 components/, app/, stitch-source/ (참조용 원본 HTML), tailwind.config.js, package.json, tsconfig.json 등의 프로젝트 구성 파일이 포함됩니다.

• 특정 스크린만 변환할 수 있나요? 문서화된 옵션에 screenIds 설정이 있어 특정 스크린 ID를 전달해 부분 집합 변환 가능; 기본은 “모든 스크린”입니다.

대안

• 수동 Stitch-to-React 변환: 컴포넌트와 Tailwind 스타일을 직접 재구축. 소규모 프로젝트에는 가능하지만 JSX 속성 엣지 케이스에서 보통 더 오래 걸리고 오류가 발생하기 쉽습니다.
• AI 어시스턴트와 프롬프트 기반 HTML-to-React/Next.js 변환: 내보낸 HTML/마크업을 LLM에 보내 변환. 컴파일러 접근과 달리 className/속성 문제와 중복 구조를 수정하기 위해 더 많은 반복이 필요할 수 있습니다.
• 디자인-to-코드용 범용 템플릿 생성기: 디자인 자산에서 React/Next.js 코드를 스캐폴딩하는 도구 사용. Stitch 전용 컴파일러처럼 Stitch 고유 컴포넌트 구조, Tailwind 테마 세부 사항, 또는 내장 마커를 보존하지 않을 수 있습니다.
• 컴포넌트 우선 UI 재구현: 각 스크린을 별도 React 구현 작업으로 간주하고 공유 컴포넌트를 직접 구축. 최대 제어를 제공하지만 변환 작업을 생성이 아닌 개발로 완전히 전환합니다.