Storefront Scaffolding - Hiveku Builder

Once a Shopify connection is active, the AI agent can scaffold the entire storefront in one prompt. This page covers what gets generated and how the pieces fit together.

The one-prompt flow

“Build me a shop based on my Shopify products.”

The agent calls shopify_scaffold_product-detail-route. That single call writes a working storefront with:

/products — server-rendered product list
/products/[handle] — server-rendered product detail with full Product JSON-LD (including aggregateRating populated from reviews when present)
/cart — cart page with line edit, qty change, remove
/api/cart — cart route handler (Storefront API mutations)
/api/revalidate — signed-token cache invalidation endpoint
/api/shopify-products — server-side products fetch for client components that can’t read server-only env vars
<CartProvider> + <CartDrawer> + <CartButton> + <ProductVariantPicker> components
The CRO defaults bundle (free shipping, urgency, recently viewed, trust badges)
<ProductReviews> server component on the PDP
/account/write-review — review submission page (linked from workflow review-request emails)

What ships in HTML on first byte

The wedge over Lovable / Bolt / v0 is what the page looks like before any client JavaScript runs. View-source on a deployed /products/<handle> shows:

Product title, description (server-rendered)
Price + compare-at-price
Image with width/height attributes (for CLS)
Stock urgency badge (“Only N left”) when inventory is low
A full <script type="application/ld+json"> block with the Product schema:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Single-Origin Coffee Bag",
  "description": "...",
  "sku": "COFFEE-001-12OZ",
  "brand": { "@type": "Brand", "name": "Roastline" },
  "image": ["https://cdn.shopify.com/..."],
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.7,
    "reviewCount": 23,
    "bestRating": 5,
    "worstRating": 1
  },
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "18.00",
    "availability": "https://schema.org/InStock",
    "url": "/products/single-origin-coffee-bag"
  }
}

Plus a BreadcrumbList JSON-LD. Both are picked up by Google’s rich-snippet scanner and by AI search crawlers like ChatGPT and Perplexity that don’t run JS.

aggregateRating only renders when at least one approved review exists. Google’s structured-data validator flags ratings with reviewCount: 0 as invalid markup, so we skip it for products with no reviews yet.

File layout the scaffolder writes

Hiveku project (greenfield, default @/* → ./src/* alias):

app/
├── products/
│   ├── page.tsx                    # list
│   └── [handle]/page.tsx           # detail (with JSON-LD)
├── cart/
│   └── page.tsx                    # cart page
├── api/
│   ├── cart/route.ts               # cart mutations
│   ├── revalidate/route.ts         # cache invalidation
│   └── shopify-products/route.ts   # client-component fetch helper
└── account/
    └── write-review/page.tsx       # review submission

src/
├── lib/shopify/
│   └── storefront-client.ts        # Storefront API client + cart fragment + types
└── components/
    ├── cart/
    │   ├── CartContext.tsx         # CartProvider, CartDrawer, CartButton, useCart
    │   └── ProductVariantPicker.tsx # variant + selling-plan picker
    └── cro/
        ├── FreeShippingBar.tsx
        ├── StockUrgency.tsx
        ├── RecentlyViewed.tsx
        ├── TrustBadges.tsx
        └── ProductReviews.tsx

For non-greenfield projects (e.g. @/* → ./* with no src/ wrapper), the scaffolder rewrites src/components/... paths to components/... automatically. See Retrofitting for the full alias-aware behavior.

The cart contract

Cart state follows a deliberate model:

Server is the source of truth for cart contents. Storefront API holds the canonical cart object.
Cookie holds the cart id — HttpOnly, set by the route handler on every mutation.
<CartProvider> holds local UI state (open/close drawer, last-fetched cart, loading flag).
No client-side reconciliation — every mutation re-renders with whatever Shopify returned.

This avoids the classic stale-cart-vs-actual-cart drift. The drawer always shows what Shopify thinks the cart contains.

Layout integration

Cart-bearing scaffolds (cart, product-detail-route, subscriptions) require <CartProvider> to wrap the app. The scaffolder response includes needsLayoutWrapper: true when this hasn’t been done yet. The AI agent should add this to your root app/layout.tsx:

import { CartProvider, CartDrawer } from '@/components/cart/CartContext'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <CartProvider>
          {children}
          <CartDrawer />
        </CartProvider>
      </body>
    </html>
  )
}

Without this wrapper, useCart() throws and the variant picker crashes on first render.

Available scaffold features

The AI agent can scaffold any of these on demand. Most users only need product-detail-route (the all-in-one); the narrower scaffolds exist for projects with custom PDPs that want to layer specific pieces in.

Scaffold feature	Files	Use when
`product-detail-route`	All of the above	”Build me a shop.” Default for greenfield.
`cart`	Cart route + components only	You have product pages but no cart yet
`customer-account`	`/account/login` + callback + dashboard + orders	Add sign-in + order history
`subscriptions`	`/account/subscriptions` + actions	Customer self-service for subs (Subscriptions)
`reviews`	Standalone reviews bundle	Custom PDP that needs reviews layered in
`sitemap`	`app/sitemap.ts`	SEO — paginated product + collection URLs
`storefront-client`	Just the lib	You’re building everything else manually
`revalidate-route`	Just the cache invalidation route	Same as above

Use AI prompts like:

“Scaffold the customer account flow for my Shopify store.” “Add subscriptions to my product pages.” “Generate a sitemap for my Shopify products.”

The agent calls the right tool and reports back what files landed.

Idempotency

Every scaffolder is idempotent — running the same scaffold twice doesn’t overwrite existing files. The response separates written (files newly created) from skipped (files that already existed). To force overwrite, the AI agent can pass overwrite: true when explicitly asked to upgrade a file.

Env vars wired automatically at deploy

When you deploy a project with a Shopify connection, Hiveku injects:

Env var	Used by	Public?
`SHOPIFY_SHOP_DOMAIN`	Server-side queries	No
`NEXT_PUBLIC_SHOPIFY_SHOP_DOMAIN`	Client cart helpers	Yes
`NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN`	Storefront GraphQL from client + server	Yes (per Shopify’s design — Storefront tokens are shop-scoped + rate-limited)
`SHOPIFY_ADMIN_TOKEN`	Server-only Admin GraphQL	No — server only
`SHOPIFY_API_VERSION`	All Shopify API calls	No
`SHOPIFY_REVALIDATION_TOKEN`	Webhook → site cache invalidation HMAC	No
`NEXT_PUBLIC_SHOPIFY_CONNECTION_ID`	`<ProductReviews>` (scopes the public reviews fetch)	Yes
`NEXT_PUBLIC_SHOPIFY_CRO_*`	CRO bundle components	Yes
`NEXT_PUBLIC_SHOPIFY_SUBS_*`	Subscriptions UI	Yes
`NEXT_PUBLIC_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID`	Customer Account OAuth	Yes
`SHOPIFY_CUSTOMER_ACCOUNT_REDIRECT_URI`	Server-side OAuth callback	No

You don’t have to manage any of this manually. Connect → deploy → it’s wired.

Cache invalidation flow

When inventory or product data changes in Shopify:

Shopify fires a webhook

products/update, products/delete, collections/update, etc.

Hiveku verifies + dispatches

The webhook receiver at /api/webhooks/shopify verifies HMAC, looks up the connection, and finds every deployed site rendering this shop’s catalog.

Hiveku calls each site at `/api/revalidate?tag=shopify-products&token=...`

Signed-token RPC. The user’s site receives it and calls Next.js revalidateTag('shopify-products'), which invalidates ISR’d product pages.

Next request to the page re-fetches from Shopify

Stale → fresh, in seconds.

You can also force a manual bust with the AI tool shopify_admin_invalidate_cache (“My catalog looks stale”).

What’s next

CRO defaults bundle

Free shipping, urgency, recently viewed, trust badges, cart upsell.

Reviews

First-party headless reviews + JSON-LD aggregateRating.

Subscriptions

Subscribe-and-save with customer self-service.

Retrofitting an existing project

Compat check + dry-run + alias-aware paths.

​The one-prompt flow

​What ships in HTML on first byte

​File layout the scaffolder writes

​The cart contract

​Layout integration

​Available scaffold features

​Idempotency

​Env vars wired automatically at deploy

​Cache invalidation flow

​What’s next

CRO defaults bundle

Reviews

Subscriptions

Retrofitting an existing project

The one-prompt flow

What ships in HTML on first byte

File layout the scaffolder writes

The cart contract

Layout integration

Available scaffold features

Idempotency

Env vars wired automatically at deploy

Cache invalidation flow

What’s next