Struttura progetto

Un tema appena scaffoldato è un progetto standard Vite + React Router 8:

my-theme/
├── app/
│   ├── root.tsx              # App shell (layout, meta, error boundary)
│   ├── routes.ts             # The route map
│   ├── routes/
│   │   ├── home.tsx          # Shop + product grid
│   │   ├── product.tsx       # PDP with variant selection
│   │   ├── collection.tsx    # Collection page
│   │   ├── collections-index.tsx
│   │   ├── localization.tsx
│   │   └── $.tsx             # Catch-all (404)
│   ├── sections/
│   │   └── hero.tsx          # Example settings-as-data section (typed `schema` export)
│   ├── graphql/
│   │   └── queries.ts        # Storefront API queries (#graphql documents)
│   └── entry.server.tsx
├── workers/
│   └── app.ts                # Cloudflare Worker entry — builds the per-request Kotao context
├── kotao.theme.json          # Theme manifest (validated by the platform build)
├── .dev.vars                 # Local credentials (gitignored; see .dev.vars.example)
├── react-router.config.ts
├── vite.config.ts
└── wrangler.jsonc

I componenti che contano

workers/app.ts è l’entry point che la piattaforma esegue. Costruisce il contesto Kotao per ogni richiesta — i tuoi route loaders accedono all’API Storefront tramite context.storefront (il client SDK) e i dati geografici tramite context.geo.

app/routes/*.tsx sono route ordinarie di React Router. I loaders recuperano i dati tramite context.storefront; la pagina prodotto utilizza getProductOptions / getSelectedVariant da @kotao/storefront/product per la selezione della variante.

app/sections/hero.tsx mostra il pattern impostazioni‑come‑dati: un componente di sezione che esporta un schema tipizzato che i commercianti possono configurare nell’editor Workspace.

app/graphql/queries.ts contiene i tuoi documenti #graphql. bun run codegen genera risultati tipizzati dalla tua API Storefront (app/graphql/storefrontapi.generated.d.ts).

kotao.theme.json è il manifest del tema. Il build della piattaforma lo valida ad ogni deploy — mantienilo sotto controllo.

Scripts

Comando	Cosa fa
bun run dev	Server di sviluppo locale in workerd (vite dev).
bun run build	Build di produzione (vite build).
bun run codegen	GraphQL tipizzato dai tuoi documenti #graphql.
bun run publish	Pacchetto sorgente committato + pubblica sul tuo storefront selezionato.
bun run typecheck	Generazione tipi React Router + tsc.