Template
Rami BitarandClaude Opus 5.5
e09bc0e1fe
The sandbox loads Vite's native tools as WASI (NAPI_RS_FORCE_WASI=error) and only ships glue for rolldown 1.1.x. Vite 8.3 pulls rolldown 1.2.x, whose binding needs emnapi 2.0 alpha, so boot failed with 'WASI binding not found'. Match the runtime-host harness TanStack sample instead: - Pin vite 8.1.3, rolldown + @rolldown/binding-wasm32-wasi 1.1.4, @vitejs/plugin-react 6.0.0, tailwindcss + @tailwindcss/vite 4.3.1 (exact versions: the sandbox resolves package.json, not yarn.lock) - Drop Nitro (it brings rolldown 1.2.x) and the Vercel config - Hono now sits in src/server.ts, Start's server entry, routing /api/* ahead of start.fetch, as in the harness - dev runs 'vite dev --host 0.0.0.0 --port 3000'; config is .mjs - Await product recommendations in the loader to fix a hydration mismatch between the SSR skeleton and the settled client render Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
69 lines
3.4 KiB
Markdown
69 lines
3.4 KiB
Markdown
# Vite Shopify Storefront
|
|
|
|
A server-rendered Shopify storefront built with Vite, TanStack Start (TanStack
|
|
Router + TanStack Query), Hono and Tailwind CSS v4. `@shopify/hydrogen` is used
|
|
only as the Storefront API client and for typed `gql()` documents. It's a port
|
|
of `nextjs-templates/shopify-storefront` without the AI store assistant.
|
|
|
|
Runs in the nodesandbox runtime: `npm install` → `npm run dev` → port 3000.
|
|
|
|
## Getting started
|
|
|
|
```sh
|
|
cp .env.example .env.local # optional; without it the store is mock.shop
|
|
corepack enable # uses the Yarn 4 pinned in package.json
|
|
yarn install
|
|
yarn dev # http://localhost:3000
|
|
```
|
|
|
|
| Script | What it does |
|
|
| ---------------- | --------------------------------------------------------- |
|
|
| `yarn dev` | Vite dev server with SSR and the Hono `/api` routes |
|
|
| `yarn build` | Production build to `dist/` |
|
|
| `yarn typecheck` | `tsc` plus `hydrogen gql check` for the GraphQL documents |
|
|
|
|
## nodesandbox compatibility
|
|
|
|
The sandbox runs Vite's native tools as WebAssembly (`NAPI_RS_FORCE_WASI`), and
|
|
its installer resolves from `package.json` ranges rather than `yarn.lock`. So:
|
|
|
|
- `vite` is pinned to **8.1.3**, which uses rolldown 1.1.x; `rolldown` and
|
|
`@rolldown/binding-wasm32-wasi` are pinned to **1.1.4**. Rolldown 1.2.x's
|
|
WASI binding needs glue the runtime doesn't support ("WASI binding not
|
|
found"). Bump these only together with the runtime.
|
|
- `@vitejs/plugin-react` (6.0.0) and Tailwind (4.3.1) match the harness samples.
|
|
- No Nitro: it brings its own rolldown 1.2.x.
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
server.ts Start's server entry: Hono routes /api/*, the rest goes to Start
|
|
router.tsx Router + per-request QueryClient, SSR query integration
|
|
routes/ File routes; loaders prefetch into TanStack Query
|
|
server/
|
|
app.ts Hono API
|
|
account.ts login, logout, register, recover, reset, activate, me
|
|
account.functions.ts server functions for account reads in loaders
|
|
hooks/ TanStack Query options + hooks over the Storefront API
|
|
services/shopify Storefront client, catalogue and customer functions
|
|
graphql/ Typed `gql()` documents
|
|
components/ Storefront UI (header, cart drawer, product detail, ...)
|
|
```
|
|
|
|
## How the Next.js pieces map
|
|
|
|
| Next.js | Here |
|
|
| ---------------------------------- | ---------------------------------------------------- |
|
|
| `app/**/page.tsx` | `src/routes/**` (TanStack file routes) |
|
|
| `generateMetadata` / `metadata` | route `head()` via `src/lib/seo.ts`, server-rendered |
|
|
| Server components fetching data | route `loader`s seeding TanStack Query, dehydrated to the client |
|
|
| `app/api/account/*` route handlers | `src/server/account.ts` (Hono) |
|
|
| `next/headers` cookies | `hono/cookie`, and `getCookie` in server functions |
|
|
| `next/image` | `src/components/ui/image.tsx` (Shopify CDN `srcset`) |
|
|
| `NEXT_PUBLIC_*` env | `VITE_*` env (`VITE_SHOPIFY_DOMAIN` defaults to mock.shop) |
|
|
|
|
Cart and catalogue reads after the first page load go straight from the browser
|
|
to the Storefront API with the public token. Account requests stay on the
|
|
server, so the customer access token never reaches client JavaScript.
|