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>
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
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:
viteis pinned to 8.1.3, which uses rolldown 1.1.x;rolldownand@rolldown/binding-wasm32-wasiare 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 loaders 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.