Development example for exercising Hydrogen APIs in SvelteKit. This is not a starter template. See
../README.mdfor context.
Port of the canonical examples/core design to SvelteKit 2 with Svelte 5 (runes mode).
- SvelteKit's server
load(+page.server.ts) as the data path — every route fetches its data on the server before rendering. - Colocated GraphQL queries (the route owns its query and types).
- Core Hydrogen primitives for cart, product variant selection, collection filtering/sorting, and Shop Pay without framework bindings.
- File-based routes:
src/routes/+page.svelte,src/routes/collections/[handle]/+page.svelte, etc. - Shared chrome (
Header,Footer) lives at the root layout insrc/routes/+layout.svelte, not per-route. - Tailwind v4 via
@tailwindcss/vite— the design's@themetokens live insrc/app.css. @sveltejs/adapter-nodesopnpm startactually serves the SSR build (node build).
| Route | Source | Status |
|---|---|---|
/ |
examples/core/reference/home.html |
Live: hero is static; featured products grid pulls from products(first: 3) |
/collections |
examples/core/reference/collections.html |
Live: queries collections(first: 12) |
/collections/:handle |
examples/core/reference/collection.html |
Live: queries collection(handle:) with up to 24 products, URL-synced filters, sort, and active filter chips |
/products/:handle |
examples/core/reference/product.html |
Live: gallery, URL-synced variant options, add-to-cart, Shop Pay, and related products |
/cart |
(Hydrogen primitive) |
Live: optimistic line updates, discount codes, order note, totals, checkout, and Shop Pay |
/blogs/news |
(new) | Live: blog(handle:"news") { articles(first: 10) }, first article rendered as featured |
/blogs/news/:handle |
(new) | Live: articleByHandle, contentHtml rendered with {@html} |
/account |
(new) | Live: Customer Account OAuth session, basic customer name/email, logout form |
/account/login |
(new) | Live: Hydrogen Customer Account handler starts OAuth and stores pending PKCE state |
POST /account/logout |
(new) | Live: Hydrogen Customer Account handler clears session and redirects with 303 See Other |
- Live: product data, collection data, prices, images, URL-synced options, cart mutations, collection filters/sort, checkout links, Shop Pay buttons, blog articles, Customer Account login/session state, basic customer identity, logout.
- Stubbed: hero links, search, newsletter form.
The account flow uses createCustomerSession and createCustomerAccountServerHandlers from @shopify/hydrogen/customer-account, Customer Account values from examples/shared/config.ts, and an encrypted HttpOnly __Host- cookie adapter from examples/shared/customer-session.ts.
Customer Account OAuth requires a public HTTPS origin. To test locally without a tunnel, run:
pnpm --filter @shopify/hydrogen-example-sveltekit dev:httpsThe local HTTPS plugin provisions the certificate, links an unlinked Hydrogen storefront, and pushes the Customer Account callback, JavaScript origin, and logout URLs. If automatic setup is unavailable, it prints the values for manual configuration.
# from the repo root
pnpm install
pnpm --filter @shopify/hydrogen-example-sveltekit devThen open http://localhost:5173.
These are calls/patterns that would benefit from a @shopify/hydrogen helper as the core package grows:
storefrontClient.graphql()fromevent.locals.storefrontClient— now uses the request-scoped client created insrc/hooks.server.tswithgql.tadafor zero-config type inference. Error normalization and request-id propagation are handled by the core client.formatMoney()insrc/lib/money.ts— every example needs money formatting from aMoneyV2-shaped object.ProductCard.sveltereads a narrow product shape (handle,title,featuredImage,priceRange.minVariantPrice). A core fragment + type for "product card" would let routes share GraphQL fragments instead of re-listing fields.- Option value swatch data is exposed through
createProductFormStore().getState().options[].values[].swatch, so selectors can render API-backed swatches withvalue.swatch.
- Framework bindings: this example intentionally uses core primitives directly. If Svelte bindings are added later, compare them against
src/lib/cart.ts,src/lib/collection.ts, andsrc/lib/components/ProductPurchasePanel.svelte.