HolyStitch

What is HolyStitch?

HolyStitch is an MCP (Model Context Protocol) tool that compiles a Google Stitch project into a working Next.js codebase. Instead of asking a model to “guess” a conversion, it reads your Stitch project via the Stitch API and generates complete JSX/Next.js output files.

Its core purpose is to turn Stitch screens into a React/Next.js project on disk in a deterministic way, including component structure, styling setup, and preserved source HTML for reference—so you can review the result and complete any remaining checklist items.

Key Features

• Stitch API ingestion (by project ID): Fetches every screen from your Stitch project using the Stitch API, using a Stitch project ID you provide.
• Structured React compilation (not prompting): Parses components based on Stitch-embedded HTML markers (e.g., <!-- ComponentName -->) and writes valid React JSX.
• Deterministic Next.js project output: Produces a Next.js project directory containing app/, components/, and supporting files, ready to install and run.
• Shared component extraction and deduplication: Detects components shared across multiple screens and writes them once in components/ instead of duplicating them per page.
• Tailwind theme extraction: Extracts the exact Tailwind theme configuration, including colors, fonts, and dark mode settings, and writes it to tailwind.config.js.
• JSX/HTML edge-case handling: Performs common JSX-safe conversions and normalization, including class→className, for→htmlFor, conversion of inline style strings into style objects (including url(), calc(), var(), and font-variation-settings), correct icon font rendering (e.g., Material Symbols/Icons), escaped code blocks inside <pre><code>, and duplicate attribute handling.

How to Use HolyStitch

1. Build the tool locally
   • Clone and build:
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • Note the full path to the built folder (e.g., /Users/alice/holystitch).
2. Get a Stitch API key
   • Copy your API key from your Stitch project settings.
3. Configure your MCP host (Claude Desktop / Cursor / Windsurf / other MCP hosts)
   • Point the MCP host to the built package (using the built dist/index.js path) and set STITCH_API_KEY.
   • Example for Claude Desktop:
     • Add an entry to claude_desktop_config.json with command: "node", args: ["<full path>/dist/index.js"], and env: { "STITCH_API_KEY": "your-api-key-here" }.
4. Provide your Stitch project ID
   • Use the project ID from the Stitch URL (the repo documentation shows it as part of https://stitch.withgoogle.com/project/<projectId>).
5. Run the conversion
   • Ask your AI assistant (connected to the MCP server) to convert the Stitch project ID into a Next.js app at the destination folder.
   • The tool writes the project files to disk; the AI can then help with follow-up checklist items (like routing, fonts, or any remaining edge-case JSX) that require human review.

Use Cases

• Convert existing Stitch landing pages into a Next.js app: Compile Stitch screens into React components and app/ routes so the design becomes runnable code.
• Handle large multi-screen Stitch projects with shared UI: Use component deduplication to extract repeated sections (e.g., nav bars, footers, hero sections) into shared components.
• Preserve styling configuration exactly: Extract the same Tailwind theme (colors, fonts, and dark mode config) into tailwind.config.js rather than recreating styles manually.
• Reduce LLM guesswork in HTML-to-JSX conversion: Rely on the compiler’s specific JSX safety rules (attribute renames, inline style parsing, escaped code blocks) to avoid common conversion failures.
• Generate a reviewed codebase for iterative development: Start from a generated Next.js project (with stitch-source/ preserved for reference) and then adjust functionality and routing with your own development workflow.

FAQ

• Does HolyStitch use AI tokens to convert my Stitch project? The repository description states it is “compiled, not prompted” and claims “zero tokens” for the conversion itself.

• What do I need to provide to run a conversion? You provide a Stitch project ID and set STITCH_API_KEY in your MCP host configuration.

• What framework does it generate? The documented default output is a Next.js project. The tool also mentions an option to use vite as a framework, though Next.js is the primary focus in the output examples.

• What ends up in the generated folder? The example output includes components/, app/, stitch-source/ (original HTML kept for reference), tailwind.config.js, and project configuration files like package.json and tsconfig.json.

• Can it convert only certain screens? The documented options include a screenIds setting that can be used to pass specific screen IDs to convert a subset; the default is “all screens.”

Alternatives

• Manual Stitch-to-React conversion: Rebuild components and Tailwind styles by hand. This can work for small projects but typically takes longer and is more error-prone for JSX attribute edge cases.
• Prompt-based HTML-to-React/Next.js conversion with an AI assistant: Send the exported HTML/markup to an LLM for transformation. Unlike a compiler approach, it may require more iteration to correct className/attribute issues and duplicated structures.
• Generic template generators for design-to-code: Use tools that scaffold React/Next.js code from design assets. These may not preserve Stitch-specific component structure, Tailwind theme details, or embedded markers the way a Stitch-aware compiler does.
• Component-first UI reimplementation: Treat each screen as a separate implementation task in React and build shared components yourself. This gives maximum control but shifts the conversion work entirely to development rather than generation.