create-magic-storefront 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-magic-storefront",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scaffold a Next.js storefront on the MagicStore Storefront API v2",
   "license": "MIT",
   "type": "module",
@@ -18,8 +18,8 @@
     "esbuild": "^0.27.0"
   },
   "devDependencies": {
-    "@magicstoreai/hydrogen": "0.4.0",
-    "@magicstoreai/storefront-client": "0.4.0",
+    "@magicstoreai/hydrogen": "0.5.0",
+    "@magicstoreai/storefront-client": "0.5.0",
     "@types/node": "^26.6.2",
     "react": "^19.3.0",
     "tsup": "^8.5.1",

package/template/.env.example

@@ -10,6 +10,11 @@ MAGICSTORE_API_URL=
 # browser calls go through this app's /storefront-api proxy (app/storefront-api/[...path]).
 NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN=
 
+# Optional. Who holds the buyer's sign-in tokens and cart id: "server" (default) keeps them in httpOnly
+# cookies behind app/storefront-api, out of reach of page JavaScript; "browser" keeps them in
+# localStorage. A public storefront token (below) always means "browser".
+MAGICSTORE_CREDENTIALS=
+
 # Optional. The storefront access token (msf_…) the server sends with its reads: the API then serves
 # this storefront's own theme, and theme previews work (they need it). Server-only; when empty, the
 # public token below is used, else the shop is found by its domain.

package/template/AGENTS.md

@@ -25,7 +25,10 @@ each error code means — then `PAGES.md` for how each page type is built, and
   `/seo`, `/theme` or `@magicstoreai/storefront-client`. `npx create-magic-storefront check` must pass.
 - Never compute money: render `Money` values with `<Money>` / `formatMoney`, totals from the cart
   and the checkout.
-- Cart id, checkout id, tokens, OTP codes, phone numbers: never logged, never in a URL.
+- Cart id, checkout id, tokens, OTP codes, phone numbers: never logged, never in a URL. By default
+  the browser never holds them at all: `app/storefront-api` keeps them in httpOnly cookies and
+  pages see `"current"` (`MAGICSTORE_CREDENTIALS`, `lib/upstream.ts`). Never read or parse a cart
+  or checkout id — pass back what the API returned.
 - Public reads render on the server through `lib/api.ts` (cached by tag, revalidated by the
   webhook). Anything personal — cart, customer, wishlist — lives in client components under
   `MagicStoreProvider` (`app/providers.tsx`).
@@ -68,7 +71,7 @@ screenshot every page type at 390 and 1280px, fix what you see. Interactive UI f
 | `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                    |
 | `lib/api.ts`                    | The server-side client (`nextCacheFetch`), `orNotFound`                                                        |
 | `app/providers.tsx`             | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                       |
-| `app/storefront-api/[...path]`  | Same-origin proxy for browser calls without a public storefront token                                          |
+| `app/storefront-api/[...path]`  | Same-origin proxy (`createStorefrontProxy`); holds tokens and cart / checkout ids in httpOnly cookies          |
 | `app/api/magicstore/webhook`    | Signed webhook → `revalidateTag`                                                                               |
 | `app/api/magicstore/preview`    | Theme editor preview: signed token → draft mode; pages pass `themePreview()` (`lib/preview.ts`) as `preview`   |
 

package/template/PAGES.md

@@ -30,6 +30,15 @@ errors).
 Every page renders per request (`dynamic = 'force-dynamic'` in `app/layout.tsx`): the shop is the
 API's, not the build's. The fetch cache still spares the API.
 
+### Who holds the buyer's credentials
+
+By default (`MAGICSTORE_CREDENTIALS` unset or `server`, `lib/upstream.ts`) every browser call goes
+through `app/storefront-api`, which keeps the sign-in tokens and the cart and checkout ids in
+httpOnly cookies. Page JavaScript only ever sees `"current"` in their place — `cart.id`,
+`checkout.id`, the session's tokens — and passes it back as is. Choose `browser` only when a public
+storefront token sends the browser straight to the API; then the tokens and the cart id live in
+`localStorage`.
+
 ## Layout — `app/layout.tsx`
 
 - Reads `api.shop()` and the navigation (`api.collectionsIndex` or `api.menusShow({ path: { handle: 'main' } })`).

package/template/app/layout.tsx

@@ -11,6 +11,7 @@ import { TelegramShell } from '@/components/telegram-shell';
 import { api, locale } from '@/lib/api';
 import { themePreview } from '@/lib/preview';
 import { brandStyle } from '@/lib/brand';
+import { credentialsMode } from '@/lib/upstream';
 import { messages } from '@/lib/i18n';
 import theme from '@/theme';
 import { Providers } from './providers';
@@ -51,7 +52,7 @@ export default async function RootLayout({ children }: { children: ReactNode })
         {shop.features.telegramBot && (
           <Script src={TELEGRAM_WEB_APP_SCRIPT} strategy="beforeInteractive" />
         )}
-        <Providers shop={shop}>
+        <Providers shop={shop} credentials={credentialsMode()}>
           <TelegramShell />
           {announcement && <p className="site-announcement">{announcement}</p>}
           <header className="site">

package/template/app/providers.tsx

@@ -9,13 +9,22 @@ const locale = process.env.NEXT_PUBLIC_MAGICSTORE_LOCALE || 'ru';
 
 /**
  * With a public storefront token the browser calls the shop's API directly (the token lists this
- * origin); without one, it goes through this app's same-origin proxy (app/storefront-api).
+ * origin); without one, it goes through this app's same-origin proxy (app/storefront-api), which by
+ * default also holds the buyer's credentials. `credentials` comes from the server
+ * (`credentialsMode()` in the layout), so the proxy and the provider always agree.
  */
-const connection = token
-  ? { shopDomain: process.env.NEXT_PUBLIC_MAGICSTORE_SHOP_DOMAIN!, storefrontToken: token }
-  : { baseUrl: '/storefront-api' };
-
-export function Providers({ shop, children }: { shop: Shop; children: ReactNode }) {
+export function Providers({
+  shop,
+  credentials,
+  children,
+}: {
+  shop: Shop;
+  credentials: 'browser' | 'server';
+  children: ReactNode;
+}) {
+  const connection = token
+    ? { shopDomain: process.env.NEXT_PUBLIC_MAGICSTORE_SHOP_DOMAIN!, storefrontToken: token }
+    : { baseUrl: '/storefront-api', credentials };
   return (
     <MagicStoreProvider {...connection} shop={shop} locale={locale}>
       <PageViews />

package/template/app/storefront-api/[...path]/route.ts

@@ -3,81 +3,26 @@
  * identifies the shop by the request's host and CORS admits only origins a token lists, so the
  * browser talks to this route and this route talks to the shop — with the shop's host, and the
  * buyer's address in X-Forwarded-For. Only the API's own headers pass, both ways.
+ *
+ * By default it also holds the buyer's credentials (`credentialsMode()`): session tokens and the
+ * cart and checkout ids live in httpOnly cookies, and the browser only ever sees "current".
  */
-import { upstreamBaseUrl } from '@/lib/upstream';
+import { createStorefrontProxy, type StorefrontProxy } from '@magicstoreai/hydrogen/server';
 
-const upstream = upstreamBaseUrl();
+import { credentialsMode, upstreamBaseUrl } from '@/lib/upstream';
 
-const REQUEST_HEADERS = [
-  'accept',
-  'accept-language',
-  'authorization',
-  'content-type',
-  'idempotency-key',
-  'if-none-match',
-  'x-anonymous-id',
-  'x-checkout-id',
-  'x-request-id',
-  'x-session-id',
-];
+let proxy: StorefrontProxy | null = null;
 
-const RESPONSE_HEADERS = [
-  'cache-control',
-  'content-language',
-  'content-type',
-  'etag',
-  'location',
-  'ratelimit-limit',
-  'ratelimit-remaining',
-  'ratelimit-reset',
-  'retry-after',
-  'x-request-id',
-];
-
-async function proxy(
+async function handle(
   request: Request,
   { params }: { params: Promise<{ path: string[] }> },
 ): Promise<Response> {
+  const upstream = upstreamBaseUrl();
   if (upstream === null) {
     return new Response('MAGICSTORE_SHOP_DOMAIN is not set', { status: 500 });
   }
-  const { path } = await params;
-  const incoming = new URL(request.url);
-  const target = new URL(`${upstream}/${path.map(encodeURIComponent).join('/')}`);
-  target.search = incoming.search;
-
-  const headers = new Headers();
-  for (const name of REQUEST_HEADERS) {
-    const value = request.headers.get(name);
-    if (value !== null) {
-      headers.set(name, value);
-    }
-  }
-  const client = request.headers.get('x-forwarded-for');
-  if (client) {
-    headers.set('x-forwarded-for', client);
-  }
-
-  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
-  const answer = await fetch(target, {
-    method: request.method,
-    headers,
-    body: hasBody ? await request.arrayBuffer() : undefined,
-    cache: 'no-store',
-    redirect: 'manual',
-  });
-
-  const out = new Headers();
-  for (const name of RESPONSE_HEADERS) {
-    const value = answer.headers.get(name);
-    if (value !== null) {
-      out.set(name, value);
-    }
-  }
-  return new Response(answer.status === 204 || answer.status === 304 ? null : answer.body, {
-    status: answer.status,
-    headers: out,
-  });
+  proxy ??= createStorefrontProxy({ upstream, credentials: credentialsMode() });
+  return proxy(request, (await params).path);
 }
 
-export { proxy as DELETE, proxy as GET, proxy as PATCH, proxy as POST, proxy as PUT };
+export { handle as DELETE, handle as GET, handle as PATCH, handle as POST, handle as PUT };

package/template/lib/upstream.ts

@@ -10,3 +10,24 @@ export function upstreamBaseUrl(): string | null {
   const domain = process.env.MAGICSTORE_SHOP_DOMAIN;
   return domain ? `https://${domain}/api/v2/storefront` : null;
 }
+
+/**
+ * Who holds the buyer's credentials. `'server'` (the default): `app/storefront-api` keeps the session
+ * tokens and the cart and checkout ids in httpOnly cookies, and the browser only sees "current".
+ * `MAGICSTORE_CREDENTIALS=browser` opts out. A public storefront token sends the browser straight to
+ * the API, past the proxy, so it means `'browser'` — and asking for `'server'` with one is an error.
+ */
+export function credentialsMode(): 'browser' | 'server' {
+  const explicit = process.env.MAGICSTORE_CREDENTIALS || null;
+  const publicToken = Boolean(process.env.NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN);
+  if (explicit !== null && explicit !== 'server' && explicit !== 'browser') {
+    throw new Error(`MAGICSTORE_CREDENTIALS must be "server" or "browser", not "${explicit}".`);
+  }
+  if (explicit === 'server' && publicToken) {
+    throw new Error(
+      'MAGICSTORE_CREDENTIALS=server needs every browser call to go through app/storefront-api: ' +
+        'unset NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN, or set MAGICSTORE_CREDENTIALS=browser.',
+    );
+  }
+  return explicit === 'browser' || publicToken ? 'browser' : 'server';
+}

package/template/llms.txt

@@ -101,6 +101,18 @@ The cart id and the checkout id are credentials. Never log them and never put th
 query string. A guest proves an order with the `X-Checkout-Id` header. The same goes for tokens,
 OTP codes and full phone numbers.
 
+Who holds them is a choice (`MagicStoreProvider credentials`):
+
+- `'server'` — the starter's default. Every browser call goes through a same-origin
+  `createStorefrontProxy({ credentials: 'server' })` (`/server`; the starter's
+  `app/storefront-api`). It keeps the access and refresh tokens and the cart and checkout ids in
+  httpOnly cookies; JavaScript, `localStorage` and every body it sees hold the literal `"current"`
+  instead (`cart.id === 'current'`, `checkoutsStore({ body: { cartId: cart.id } })` just works). A
+  401 the proxy flags with `x-session-expired` refreshes once and retries once; the proxy never
+  refreshes on its own.
+- `'browser'` — the tokens and the cart id live in `localStorage`. Required when a public
+  storefront token sends the browser straight to the API (the proxy is not in the path).
+
 ## Cart → checkout → payment
 
 1. The first `useCart().addLine(…)` creates the cart; its id is stored for you. Every cart answer
@@ -142,6 +154,7 @@ for buyers), quote `error.requestId` when reporting. GET calls retry on 429 / 5x
 | `OTP_INVALID`                                    | Let the buyer re-type the code.                              |
 | `OTP_EXPIRED`                                    | Ask for a new code.                                          |
 | `NETWORK_ERROR`, `ABORTED`                       | No answer (client-side): offer to try again.                 |
+| `INVALID_RESPONSE`                               | The API answered 2xx with an unreadable body: report it.     |
 
 The full list, with the `meta` each code carries, is in the backend's `docs/api/v2/standards.md`.