Lokale Entwicklung

Dev-Server

bun run dev

vite dev führt dein Theme via @cloudflare/vite-plugin in workerd aus — derselben Runtime wie in Produktion, mit Hot Reload. Was lokal läuft, läuft auch deployt.

Zugangsdaten: `.dev.vars`

Deine Loader sprechen mit einer echten Storefront-API. Der Scaffolder schreibt die Verbindung nach .dev.vars (gitignored); falls du den Schritt übersprungen hast, kopiere das Beispiel:

cp .dev.vars.example .dev.vars

Die Variablen, die im Alltag zählen:

Variable	Zweck
`STOREFRONT_API_ENDPOINT`	Die Storefront-API-URL deines Shops
`STOREFRONT_API_TOKEN`	Ein Workspace-API-Key für lokale Reads
`KOTAO_SHOP_ID` / `KOTAO_SITE_ID`	Shop / Storefront-Site, aus der die Daten kommen

Typisiertes GraphQL

Schreibe Queries als #graphql-Dokumente (siehe app/graphql/queries.ts) und generiere Typen gegen deine Storefront-API:

bun run codegen

Das introspektiert $STOREFRONT_API_ENDPOINT (oder eine lokale SDL-Datei via --schema) und schreibt app/graphql/storefrontapi.generated.d.ts.

Runtime-Regeln (Untrusted Mode)

Themes laufen in Produktion als untrusted Workers. Diese Punkte funktionieren in einem naiven lokalen Setup, scheitern aber deployt:

Kein request.cf — Geo-Daten kommen stattdessen typisiert als context.geo.
Kein eval / new Function.
Kein geteilter Cache, keine fortschreitende Uhr innerhalb eines Requests — baue keine Logik darauf.

kotao storefront dev reproduziert diese Regeln lokal, wenn du dagegen testen willst.