Getting Started

Maho Storefront is a headless commerce frontend built on Cloudflare Workers with three goals:

1. Fastest End-User Experience

Every page is server-rendered at the edge - the nearest Cloudflare PoP (200+ locations globally) serves fully rendered HTML in under 100ms. A three-tier caching strategy (edge cache → KV store → origin API) means users get instant responses regardless of their region. No client-side rendering delays, no loading spinners, no layout shifts.

2. Fantastic Developer Experience

Hono.js was chosen as the framework because it's purpose-built for edge runtimes - lightweight (~14kb), fast, and ships with JSX support out of the box. Developers write familiar JSX templates that render server-side, use Hotwire Turbo for SPA-like page transitions without a JavaScript framework, and Stimulus.js for progressive client-side interactivity. Styling uses UnoCSS with DaisyUI v5 components for a token-driven, themeable design system. The component variant system makes it easy to create and swap UI variants per store without touching core logic.

3. Great SEO Experience

Full server-side rendering means search engines receive complete, crawlable HTML on every request - no JavaScript required to see content. Combined with proper semantic markup, structured data (Schema.org), and canonical URLs, the storefront is optimised for search engine indexing from the ground up.

4. Agent Ready

Built to be read and transacted on by AI agents, not just by humans and search-engine crawlers. The storefront publishes a curated /llms.txt reading list, RFC 9727 API catalog, RFC 8414 OAuth discovery, content-signal /robots.txt, KV-driven /sitemap.xml with <lastmod>, an MCP server card, and markdown content negotiation on every catalogue page — see Agent Readiness for the full surface.

Prerequisites

• Bun (auto-installed by ./maho storefront:build, or install manually)
• Wrangler CLI (installed as a dev dependency)
• A running Maho backend with the API Platform module enabled
• A Cloudflare account with Workers and KV access

Quick Start

# Clone the repository
git clone https://github.com/mageaustralia/maho-storefront.git
cd maho-storefront

# Install dependencies
bun install

# Build CSS and JS
bun run build

# Start local dev server
bun run dev

The local dev server runs at http://localhost:8787 using Wrangler's local mode with simulated KV storage.

What's Next

• Installation - detailed setup instructions
• Project Structure - understand the codebase layout
• Architecture Overview - how the system works end-to-end
• Deployment - deploy to Cloudflare Workers
• Agent Readiness - the AI-agent surface every storefront ships