One-prompt custom storefront (Lovable, v0, Cursor)

import { useStore } from "@quickshops/sdk";
import { Storefront, toStoreProducts } from "@quickshops/sdk/react";

const { buyNow, loadCatalog, getCheckoutSession } = useStore();

Build a Next.js App Router TypeScript storefront that sells via Quickshops.

SSR-first for SEO (Server Components for catalog/PDP). No publishable API keys.
Install: npm add @quickshops/sdk server-only react

Server: use ONLY useStore from @quickshops/sdk (import "server-only").
Client UI: use @quickshops/sdk/react composition primitives (Storefront.Provider, Storefront.Product slots, BuyButton, CheckoutSuccess).
Use shadcn-style theme tokens already in the project (bg-primary, text-card-foreground, etc.) — do not invent a parallel design system.
Do NOT raw-fetch api.quickshops.app from the browser. Do NOT invent pk_ / publishable keys.
Do NOT hand-roll successUrl/cancelUrl or cart cookies.
Do NOT put HEADLESS_API_KEY in client components or NEXT_PUBLIC_*.
useStore is a server factory, not a React hook — never import it in "use client" files.

Env (server only):
- HEADLESS_API_KEY=qk_...
- HEADLESS_API_URL=https://api.quickshops.app (optional)
- SITE_URL=https://this-site-absolute-https-origin

lib/quickshops.ts:
import "server-only";
import { useStore } from "@quickshops/sdk";
export const store = useStore();

Default flow = buy-now (no cart cookie):
1. Home: store.loadCatalog() → Storefront.Provider with toStoreProducts(products) and actions={{ buy: buyProduct }} → Storefront.Grid
2. Buy action: store.buyNow({ productId }) → redirect(url)
3. Success: CheckoutSuccess with store.getCheckoutSession(session_id); store.clearCartId(await cookies())

Optional cart only if needed: store.addToCart(await cookies(), { productId }), store.checkoutCart({ cartId }).

Handle error codes: CART_EMPTY, CART_MIXED_TYPES, PAYMENTS_NOT_CONFIGURED, STORE_UNPUBLISHED, RATE_LIMITED.

Ship a working SSR storefront I can set env vars on and complete a test purchase with.

HEADLESS_API_KEY=qk_...
HEADLESS_API_URL=https://api.quickshops.app
SITE_URL=https://your-custom-site.example

Browser → your Next.js server → useStore() → Stripe Checkout URL

npx skills add valtterisa/quickshops --skill quickshops-headless-storefront