AI Section Generator (Blocksmith)

AI-powered custom Shopify Liquid sections without coding. Merchants describe sections in natural language, get production-ready Liquid code with live preview, and save directly to their theme.

Stack: React Router 7, TypeScript, Prisma, Google Gemini 2.5 Flash, MongoDB, Shopify Polaris

What is this?

Blocksmith enables Shopify merchants to create custom theme sections in 4 steps:

1. Describe - Natural language prompt ("Testimonials section with 3 columns")
2. Generate - AI creates production-ready Liquid + schema + styles
3. Preview - See live rendering with real shop data
4. Save - Publish directly to theme with one click

Key Features

• AI Generation: Google Gemini 2.5 Flash produces Liquid code
• Interactive Chat: Refine sections via conversation (SSE streaming)
• Live Preview: Real-time rendering with 18 context types + 25+ filters
• Theme Publishing: Direct save to Shopify themes via GraphQL
• Dual-Action Save: Draft persistence + theme publishing
• Auto-Save: Silent background saves prevent data loss
• Hybrid Billing: Recurring + usage-based pricing
• Polaris Web Components: Native Shopify admin UX

Documentation

Quick Links:

• Quick Start - Setup in 5 minutes
• Project Overview & PDR - Features, requirements, roadmap
• Codebase Summary - 116 components, 20 services, 12 models
• Code Standards - TypeScript strict, patterns, testing
• System Architecture - Data flow, integrations, scalability

Project Status

Current Version: 1.0-beta - Phase 4 UI Feedback + Phase 01 CRO Recipes

Implemented:

• ✅ AI section generation (Google Gemini 2.5 Flash)
• ✅ Interactive chat with streaming via SSE
• ✅ Live preview with 18 context drops + filters/tags
• ✅ Theme selection and direct save to Shopify
• ✅ Dual-action save (Draft + Publish)
• ✅ Section editing with auto-save on AI generation
• ✅ Auto-save draft when AI applies version (Phase 1)
• ✅ CRO-focused recipe system for section generation (Phase 01)
• ✅ Hybrid billing (recurring + usage-based)
• ✅ Multi-tenant shop isolation
• ✅ TypeScript strict mode, 30+ test suites
• ✅ 116 React components, 20 services, 12 database models

Pending: Production deployment, Shopify write_themes scope approval

Future: Template library, versioning, marketplace, batch generation

Quick Start

Prerequisites

• Node.js: >= 20.19 or >= 22.12
• Shopify Partner Account: Create here
• Test Store: Development store or Plus sandbox
• Shopify CLI: Install here

Local Development

npm install              # Install dependencies
npm run dev              # Start dev server with tunnel
npm run build            # Build for production
npm test                 # Run tests
npm run lint             # Check code quality
npm run deploy           # Deploy to Shopify

Local development uses Shopify CLI tunnel for HTTPS. Open the app URL shown in CLI output.

Environment Variables

# Required for AI section generation
GEMINI_API_KEY=your_google_api_key

# Optional feature flags
FLAG_VERBOSE_LOGGING=true    # Enable debug logging
FLAG_USE_MOCK_AI=false       # Use mock AI in development
FLAG_USE_MOCK_THEMES=false   # Use mock themes in development

# Shopify (auto-configured by CLI)
SHOPIFY_API_KEY=...
SHOPIFY_API_SECRET=...
DATABASE_URL=file:dev.sqlite  # Dev uses SQLite, production uses PostgreSQL/MySQL

See Code Standards for full reference.

Shopify Dev MCP

This template is configured with the Shopify Dev MCP. This instructs Cursor, GitHub Copilot and Claude Code and Google Gemini CLI to use the Shopify Dev MCP.

For more information on the Shopify Dev MCP please read the documentation.

Deployment

Database: SQLite for development, PostgreSQL/MySQL/MongoDB for production Hosting Options: Google Cloud Run, Fly.io, Render, or custom Docker deployment Configuration: See Deployment Guide for detailed setup instructions

Key requirements:

• NODE_ENV=production environment variable
• MongoDB or PostgreSQL database connection
• Shopify app credentials and scopes
• Google Gemini API key for production

Troubleshooting

Database tables don't exist

• Run npm run setup or npx prisma migrate dev

Embedded app navigation breaks

• Use Link from react-router, not <a> tags
• Use redirect from authenticate.admin, not react-router

Webhooks not updating

• Define webhooks in shopify.app.toml instead of in code
• Run npm run deploy to sync

Gemini API failing

• Check GEMINI_API_KEY is set in .env
• App falls back to mock sections if key is missing

See full troubleshooting: Code Standards & Deployment Guide

Resources

• React Router docs
• Shopify App Framework
• Shopify CLI
• Polaris Components
• Shopify Admin API
• Google Gemini API