Projektstruktur

Ein frisch aufgesetztes Theme ist ein normales Vite-+-React-Router-7-Projekt:

my-theme/
├── app/
│   ├── root.tsx              # App-Shell (Layout, Meta, Error-Boundary)
│   ├── routes.ts             # Die Routen-Map
│   ├── routes/
│   │   ├── home.tsx          # Shop + Produktgrid
│   │   ├── product.tsx       # Produktseite mit Variantenauswahl
│   │   ├── collection.tsx    # Collection-Seite
│   │   ├── collections-index.tsx
│   │   ├── localization.tsx
│   │   └── $.tsx             # Catch-all (404)
│   ├── sections/
│   │   └── hero.tsx          # Beispiel-Section (settings-as-data, typisierter `schema`-Export)
│   ├── graphql/
│   │   └── queries.ts        # Storefront-API-Queries (#graphql-Dokumente)
│   └── entry.server.tsx
├── workers/
│   └── app.ts                # Cloudflare-Worker-Entry — baut den Kotao-Kontext pro Request
├── kotao.theme.json          # Theme-Manifest (wird vom Plattform-Build validiert)
├── .dev.vars                 # Lokale Zugangsdaten (gitignored; siehe .dev.vars.example)
├── react-router.config.ts
├── vite.config.ts
└── wrangler.jsonc

Die wichtigen Teile

workers/app.ts ist der Entry, den die Plattform ausführt. Er baut den Kotao-Kontext pro Request — deine Route-Loader erreichen die Storefront-API über context.storefront (den SDK-Client) und Geo-Daten über context.geo.

app/routes/*.tsx sind gewöhnliche React-Router-Routen. Loader laden Daten über context.storefront; die Produktseite nutzt getProductOptions / getSelectedVariant aus @kotao/storefront/product für die Variantenauswahl.

app/sections/hero.tsx zeigt das Settings-as-data-Muster: eine Section-Komponente mit typisiertem schema-Export, die Händler im Workspace-Editor konfigurieren können.

app/graphql/queries.ts enthält deine #graphql-Dokumente. bun run codegen erzeugt daraus typisierte Ergebnisse gegen deine Storefront-API (app/graphql/storefrontapi.generated.d.ts).

kotao.theme.json ist das Theme-Manifest. Der Plattform-Build validiert es bei jedem Deploy — es muss committet bleiben.

Skripte

Befehl	Was er tut
bun run dev	Lokaler Dev-Server in workerd (vite dev).
bun run build	Produktions-Build (vite build).
bun run codegen	Typisiertes GraphQL aus deinen #graphql-Dokumenten.
bun run publish	Committeten Quellcode paketieren + auf die gewählte Storefront publishen.
bun run typecheck	React-Router-Typegen + tsc.