---
name: build-selldone-genesis-storefront
description: "Plan, build, validate, and deploy a complete Selldone Genesis customer storefront from the official static starter and a connected Selldone MCP shop. Use for substantial, multi-stage storefront replacements or redesigns that need real catalog data, customer OAuth PKCE, basket and checkout, account flows, browser testing, and Cloudflare Workers Static Assets deployment."
---

# Build a Selldone Genesis Storefront

Build a production, brand-specific customer storefront while Selldone remains the commerce engine. Treat the latest Selldone MCP storefront resources and public AI guideline as the source of truth.

## Set expectations before starting

Tell the user, before planning or editing, that this skill is for a **complete storefront project**, not a quick shop setup or a small visual tweak. Explain that the work requires substantial time and patience across discovery, business decisions, planning, implementation, content review, browser testing, corrections, production configuration, and launch verification. AI accelerates the work but does not remove the need for repeated user review and approval.

Present the project as reviewable stages. Do not imply that one prompt will safely finish the storefront. If the user mainly needs a domain, email service, basic shop copy, policies, categories, or initial product entry, recommend the `setup-selldone-genesis-essentials` skill instead.

## Establish authoritative context

1. Verify that Selldone MCP is connected to the intended shop.
2. If it is not connected, ask the user to add the Streamable HTTP endpoint `https://selldone.com/mcp/connector`, complete Selldone's browser authorization, choose the shop and scopes, and retry a read-only call.
3. Never ask the user to paste an MCP bearer token, API key, access token, refresh token, client secret, manual token, or `shop_id` into chat. Never place MCP credentials in storefront code.
4. Call `selldone_current_connection` when available to confirm the shop context and granted scopes. Use its reconnect URL if a required scope is missing.
5. Read `selldone://guidelines/storefront-agent` before planning.
6. Invoke the `selldone_storefront_builder` prompt for the user's goal.
7. Call `selldone_storefront_plan` with the goal, business type, and enabled special flows. Use `client_framework=bootstrap_vanilla` and `server_framework=cloudflare_workers` for the official starter unless the user approves another stack.
8. Fetch the latest guideline from `https://github.com/selldone/storefront-sdk/tree/main/ai-guideline`. Begin with its `Agent.md` and `00-ai-agent-entrypoint.md`.
9. Stop and report the missing dependency if neither MCP nor the current public guideline can be read. Do not reconstruct Selldone contracts from generic ecommerce knowledge.

Prefer newer MCP and guideline contracts if they conflict with this skill. Use MCP for planning, inspection, and confirmed shop operations; never make MCP a storefront runtime dependency.

## Clone and inspect the official starter

Use the official static starter:

```bash
git clone https://github.com/pajuhaan/selldone-custom-storefront-backoffice-1.git
cd selldone-custom-storefront-backoffice-1
npm install
```

Before editing, read `AGENT.md`, `README.md`, `package.json`, `wrangler.toml`, `.env.example`, and relevant files under `docs/`. Inspect `git status` and preserve user changes.

Keep the starter architecture unless the approved plan deliberately changes it:

- Keep storefront source in `storefront/`, served at `/`.
- Keep the browser-side dashboard in `dashboard/`, served at `/dashboard/`.
- Keep the OAuth callback in `callback/`, served at `/callback/`.
- Keep shared browser modules in `shared/`.
- Keep `scripts/dev-static.mjs` development-only.
- Generate production assets into `dist/` with `scripts/build-static.mjs`.
- Deploy only `dist/` through Cloudflare Workers Static Assets.
- Do not add a production Node server, commit `dist/`, or deploy local files.

Treat Bootstrap and Vanilla JavaScript as the behavioral base, not a visual constraint. Preserve working contracts while replacing design and content for the merchant's brand.

## Plan before implementation

Resolve the goal, audience, business model, visual direction, content needs, locales, currencies, integrations, and enabled commerce modules. Derive shop facts through the connected MCP instead of guessing.

Read these guideline files as the no-skip baseline:

- `06-feature-inventory.md`
- `07-module-implementation-matrix.md`
- `_generated/route-index.md`
- `_generated/source-module-index.md`
- `_generated/api-usage-by-area.md`
- `_generated/api-url-builders.md`
- `_generated/api-url-builders-supplement.md`
- `storefront/10-product-pricing-marketplace-options.md` before product detail, pricing, variants, vendors, options, subscriptions, or basket work
- `storefront/11-checkout-payment-account-deep-dive.md` before basket, checkout, payment, orders, authentication, profile, or account work

Present a plan containing:

- Goal, assumptions, stack, brand direction, milestones, approval checkpoints, and guideline revision.
- Feature registry marked required, enabled, deferred, or not applicable.
- Route and screen map, including configured `shop-prefix-address` behavior.
- Exact API map with method, full URL, parameters, payload, auth mode, response hints, and guideline source.
- Runtime configuration, state, caching, loading, empty, error, stale, restricted, and offline behavior.
- Product types, variants, vendor choices, pricing preview, basket payloads, checkout, payment, typed orders, and account behavior.
- Public visitor, guest, authenticated customer, OAuth callback, and logout behavior.
- Page Builder content, blog, official pages, FAQ, localization, currency, accessibility, responsive behavior, security, analytics, and enabled special flows.
- Test strategy, deployment, rollback, known unknowns, and documentation gaps.

Do not start implementation until the user has seen the plan and explicitly approved the proposed scope and first stage.

## Enforce API and security boundaries

Apply these host rules to every network call:

- Use `https://xapi.selldone.com` for customer storefront commerce runtime calls.
- Use `https://gapi.selldone.com` only for explicitly documented global/platform helper flows.
- Use `https://capi.selldone.com` for documented community surfaces.
- Use `https://api.selldone.com` only for dashboard, backoffice, or admin integrations; never use it for customer storefront runtime calls.
- Use `https://selldone.com/oauth` for public-client OAuth Authorization Code with PKCE.

Resolve every call to a documented full endpoint through the guideline chain. Never invent paths, fields, scopes, pricing behavior, checkout rules, or placeholder APIs. Record a documentation gap if a contract cannot be found.

Keep only browser-safe public values in HTML meta tags: shop handle, shop ID, public OAuth client ID, domains, public API/CDN bases, and route paths. Never expose client secrets, private API keys, MCP credentials, Cloudflare tokens, or pre-issued customer tokens in HTML, JavaScript, source control, logs, or build output.

Implement customer login as a public OAuth client with Authorization Code + PKCE, `S256`, `state`, exact `redirect_uri`, `source=customer`, `prompt=consent`, and only required customer scopes. Never generate, request, or store a client secret. Keep storefront and dashboard token stores separate.

Before editing authentication, read `selldone://storefront/auth/customer-login-pkce` and call `selldone_storefront_auth_flow` with `source=customer`. Inspect clients with `selldone_shop_client_list`; create or update one for the exact production callback only after explicit user confirmation and with the tool's required `confirm=true`.

Bootstrap shop data with `GET https://xapi.selldone.com/shops/@{shop}/info`. Load `GET https://xapi.selldone.com/me` only when a customer bearer token exists. If guest shopping is enabled, persist `shop.guest_code` per visitor and send it as `S-Guest` on documented basket and checkout calls. Treat the backend basket bill as the source of truth; client price calculations are previews only.

Never pass manual tokens, headers, `S-Guest`, shop names, or shop IDs to MCP tools that derive them from the verified connection. Require explicit approval before MCP mutations and use `confirm=true` only when the selected tool requires it.

## Implement in dependency order

1. Configure shop handle, prefix URL, public API/CDN bases, locale, currency, public OAuth client ID, and callback path.
2. Build one central XAPI client with documented headers, auth, guest identity, errors, pagination, cancellation, and retries.
3. Build state for shop, customer, baskets, guest code, currency, orders, comparison, campaigns, and enabled special flows.
4. Implement routing, metadata, deep-link fallback, and configured route prefixes.
5. Implement the responsive shell, navigation, search, footer, support, dialogs, loading, empty, and error states.
6. Implement catalog browsing, categories, search, filtering, sorting, pagination, and product cards.
7. Implement product detail only after resolving product-type pricing, variants, marketplace vendors, preferences, subscriptions, stock, ratings, wishlists, and exact basket payloads.
8. Read `selldone://storefront/basket-cart-flow`, then implement basket mutations, bill refresh, receiver and delivery data, dynamic checkout forms, billing, shipping packages, promotions, gateways, payment, and pending-payment recovery in the documented sequence.
9. Implement authentication, profile, addresses, typed order history and detail, allowed order actions, returns, gift cards, wallets, comments, favorites, and logout.
10. Implement Page Builder content, blog, official pages, contact, FAQ, localization, currency, private-shop gates, popups, and every enabled special flow.

Preserve distinctions between physical, virtual, file, service, subscription, POS, Avocado, marketplace, and other enabled product or order flows. Do not collapse payment status, order status, and delivery state into one generic state. Use official Vue sources only for behavioral traceability; do not copy their UI.

Complete each approved stage, demonstrate it in a browser, report gaps, and obtain review before moving into a materially different stage or production change.

## Validate the storefront

Run the repository's supported checks:

```bash
npm install
npm run build:static
npm run preview:static
```

Verify `dist/index.html`, `dist/dashboard/index.html`, `dist/callback/index.html`, and `dist/shared/`. Run `git diff --check`; inspect `git diff` and `git status` before handoff.

Use a real browser to verify `/`, `/dashboard/`, `/callback/`, product and content deep links, SPA fallback, responsive layouts, keyboard navigation, focus visibility, meaningful alt text, loading/empty/error states, and console/network errors. Test public browsing, guest state, customer login, callback state and PKCE, token separation, logout, basket persistence, bill refresh, checkout, and at least one representative typed order flow. Never create a real charge unless explicitly authorized.

Audit every implemented call against the API map. Confirm storefront runtime calls never reach `api.selldone.com`, authenticated calls wait for tokens, guest calls preserve `S-Guest`, and no undocumented path remains. Search source and `dist/` for secrets, tokens, MCP credentials, localhost URLs, placeholder APIs, and stale sample-merchant values.

Reconcile the result against the approved feature registry, route map, endpoint catalogs, and acceptance checklist. Mark exclusions as explicit decisions instead of silently omitting them.

## Deploy to Cloudflare Workers

Treat an explicit deployment request as deployment authorization. Otherwise, stop after a verified build and request approval before changing Cloudflare, DNS, domains, Selldone OAuth clients, or production state.

Keep `wrangler.toml` configured for Workers Static Assets:

```toml
[assets]
directory = "./dist/"
not_found_handling = "single-page-application"
html_handling = "auto-trailing-slash"
```

Verify the selected account, unique Worker name, authentication, and current build:

```bash
npx wrangler whoami
npm run build:static
npx wrangler deploy
```

Use `npx wrangler versions upload` for a non-production version. For GitHub-connected Cloudflare Workers Builds, configure:

- Build command: `npm run build:static`
- Deploy command: `npx wrangler deploy`
- Non-production command: `npx wrangler versions upload`
- Root path: `/`

Configure the production custom domain, then register its exact `https://<domain>/callback/` URL on the shop's public Selldone OAuth client with explicit confirmation. Never reuse the starter's sample Worker name, domain, callback, or merchant configuration.

After deployment, smoke-test the live root, callback, dashboard if retained, deep links, assets, XAPI CORS behavior, OAuth round trip, logout, and errors. Confirm the live build contains no secrets and report the Worker URL, custom domain, version, validation performed, deferred modules, and remaining documentation gaps.