create-magic-storefront 0.3.1 → 0.5.0

package/template/app/page.tsx

@@ -1,16 +1,25 @@
-import { HomeSections } from '@/components/sections';
-import { api } from '@/lib/api';
+import { loadTemplate } from '@magicstoreai/hydrogen/server';
+import { ThemeSections } from '@magicstoreai/hydrogen/theme';
 
+import { api, locale } from '@/lib/api';
+import { themePreview } from '@/lib/preview';
+import theme, { components } from '@/theme';
+
+/**
+ * Home: the merchant's `index` template (edited in the admin's theme editor), or the theme's bundled
+ * one until the theme is pushed; the admin's draft while it previews (lib/preview.ts). It never needs `GET /home`; the `platform-home` section brings
+ * that layout in when the merchant adds it.
+ */
 export default async function Home() {
-  const { data: home } = await api.home();
-  // A shop that has not laid out its home page yet still greets buyers with its newest products.
-  const sections =
-    home.sections.length > 0
-      ? home.sections
-      : [{ id: 'default', type: 'NEW_ARRIVALS' as const, settings: { limit: null } }];
+  const [{ data: shop }, preview] = await Promise.all([api.shop(), themePreview()]);
+  const sections = await loadTemplate(api, 'index', theme, {
+    locale,
+    defaultLocale: shop.defaultLocale,
+    preview,
+  });
   return (
     <div className="home">
-      <HomeSections sections={sections} />
+      <ThemeSections sections={sections} components={components} />
     </div>
   );
 }

package/template/app/pages/[handle]/page.tsx

@@ -1,7 +1,11 @@
 import type { Metadata } from 'next';
+import { loadTemplate } from '@magicstoreai/hydrogen/server';
 import { pageMeta } from '@magicstoreai/hydrogen/seo';
+import { ThemeSections, type SectionComponents } from '@magicstoreai/hydrogen/theme';
 import { api, locale, orNotFound } from '@/lib/api';
-import { messages } from '@/lib/i18n';
+import { themePreview } from '@/lib/preview';
+import theme, { components } from '@/theme';
+import { PageContent } from '@/theme/sections/page-content';
 
 type Props = { params: Promise<{ handle: string }> };
 
@@ -12,18 +16,29 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   return { title: meta.title, description: meta.description };
 }
 
-/** A merchant's content page (about, delivery, offer…). `body` is the merchant's HTML. */
+/**
+ * A merchant's content page (about, delivery, offer…), laid out by the theme's `page` template:
+ * `page-content` shows the page's own title and body, other sections sit around it.
+ */
 export default async function ContentPage({ params }: Props) {
   const { handle } = await params;
-  const { data: page } = await orNotFound(api.pagesShow({ path: { handle } }));
+  const [{ data: page }, { data: shop }, preview] = await Promise.all([
+    orNotFound(api.pagesShow({ path: { handle } })),
+    api.shop(),
+    themePreview(),
+  ]);
+  const sections = await loadTemplate(api, 'page', theme, {
+    locale,
+    defaultLocale: shop.defaultLocale,
+    preview,
+  });
+  const pageComponents: SectionComponents<typeof theme.sections> = {
+    ...components,
+    'page-content': (props) => <PageContent {...props} page={page} />,
+  };
   return (
-    <article className="stack">
-      <h1>{page.title}</h1>
-      {page.body ? (
-        <div dangerouslySetInnerHTML={{ __html: page.body }} />
-      ) : (
-        <p className="muted">{messages(locale).nothingHere}</p>
-      )}
-    </article>
+    <div className="home">
+      <ThemeSections sections={sections} components={pageComponents} />
+    </div>
   );
 }

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/components/sections/collections.tsx

@@ -6,7 +6,8 @@ import { api } from '@/lib/api';
 
 import type { SectionOf } from './types';
 
-function CollectionTiles({
+/** Collection tiles linking to each collection; renders nothing for none. */
+export function CollectionTiles({
   collections,
   className = '',
 }: {

package/template/components/sections/product-shelves.tsx

@@ -8,7 +8,8 @@ import { messages } from '@/lib/i18n';
 
 import { SHELF_SIZE, type SectionOf } from './types';
 
-function Shelf({
+/** A titled row of product cards; renders nothing for no products. */
+export function Shelf({
   title,
   href,
   products,

package/template/lib/api.ts

@@ -1,25 +1,55 @@
 import 'server-only';
-import { MagicStoreError, createStorefrontClient } from '@magicstoreai/storefront-client';
+import {
+  MagicStoreError,
+  createStorefrontClient,
+  type StorefrontClient,
+} from '@magicstoreai/storefront-client';
 import { nextCacheFetch } from '@magicstoreai/hydrogen/server';
 import { notFound } from 'next/navigation';
 
 import { upstreamBaseUrl } from './upstream';
 
-const baseUrl = upstreamBaseUrl();
-if (baseUrl === null) {
-  throw new Error('Set MAGICSTORE_SHOP_DOMAIN or MAGICSTORE_API_URL (see .env.example).');
+export const locale = process.env.NEXT_PUBLIC_MAGICSTORE_LOCALE || 'ru';
+
+/**
+ * The storefront access token server-side reads go with (`X-Storefront-Token`), or `null` to be
+ * identified by the shop's domain. It picks this storefront's own theme, and a theme preview needs
+ * it: the preview is signed with this token's webhook secret.
+ */
+export function storefrontToken(): string | null {
+  return (
+    process.env.MAGICSTORE_STOREFRONT_TOKEN ||
+    process.env.NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN ||
+    null
+  );
 }
 
-export const locale = process.env.NEXT_PUBLIC_MAGICSTORE_LOCALE || 'ru';
+let client: StorefrontClient | null = null;
+
+function storefrontClient(): StorefrontClient {
+  if (client === null) {
+    const baseUrl = upstreamBaseUrl();
+    if (baseUrl === null) {
+      throw new Error('Set MAGICSTORE_SHOP_DOMAIN or MAGICSTORE_API_URL (see .env.example).');
+    }
+    const token = storefrontToken();
+    client = createStorefrontClient({
+      baseUrl,
+      locale,
+      ...(token ? { storefrontToken: token } : {}),
+      fetch: nextCacheFetch({ revalidate: 600 }),
+    });
+  }
+  return client;
+}
 
 /**
  * The server-side client. Public reads are cached under the tags the webhook revalidates; nothing
- * personal is ever called from here.
+ * personal is ever called from here. It is created on first use, so importing a module that uses
+ * it (a theme section, for `create-magic-storefront theme check`) needs no shop configured.
  */
-export const api = createStorefrontClient({
-  baseUrl,
-  locale,
-  fetch: nextCacheFetch({ revalidate: 600 }),
+export const api: StorefrontClient = new Proxy({} as StorefrontClient, {
+  get: (_, method) => Reflect.get(storefrontClient(), method),
 });
 
 /** Runs a read and turns the API's NOT_FOUND into the page's 404. */

package/template/lib/i18n.ts

@@ -57,6 +57,8 @@ const en = {
     `${count} ${plural('en', count, { one: 'review', other: 'reviews' })}`,
   recommendUs: (percent: number) => `${percent}% recommend us`,
   leaveReview: 'Leave a review',
+  shopNow: 'Shop now',
+  ratedOutOf: (rating: number) => `Rated ${rating} out of 5`,
   // Blog
   blog: 'Blog',
   allArticles: 'All articles',
@@ -182,6 +184,8 @@ const ru: Messages = {
     `${count} ${plural('ru', count, { one: 'отзыв', few: 'отзыва', other: 'отзывов' })}`,
   recommendUs: (percent) => `${percent}% рекомендуют нас`,
   leaveReview: 'Оставить отзыв',
+  shopNow: 'Перейти в каталог',
+  ratedOutOf: (rating: number) => `Оценка ${rating} из 5`,
   blog: 'Блог',
   allArticles: 'Все статьи',
   featured: 'Выбор редакции',
@@ -297,6 +301,8 @@ const uz: Messages = {
   reviewsCount: (count) => `${count} ta sharh`,
   recommendUs: (percent) => `${percent}% bizni tavsiya qiladi`,
   leaveReview: 'Sharh qoldirish',
+  shopNow: "Katalogga o'tish",
+  ratedOutOf: (rating: number) => `Baho: ${rating} / 5`,
   blog: 'Blog',
   allArticles: 'Barcha maqolalar',
   featured: 'Muharrir tanlovi',

package/template/lib/preview.ts

@@ -0,0 +1,21 @@
+import 'server-only';
+import { THEME_PREVIEW_COOKIE, verifyThemePreview } from '@magicstoreai/hydrogen/server';
+import { cookies, draftMode } from 'next/headers';
+
+import { storefrontToken } from './api';
+
+/**
+ * The admin's theme preview token for this request, or `null` for every ordinary visitor. Only
+ * read in draft mode (set by /api/magicstore/preview), so pages stay static and cached for
+ * everyone else; re-verified here so an expired token falls back to the live theme instead of a
+ * THEME_PREVIEW_INVALID error. Off without a storefront token: the API cannot preview a request it
+ * identifies by its domain.
+ */
+export async function themePreview(): Promise<string | null> {
+  const secret = process.env.MAGICSTORE_WEBHOOK_SECRET;
+  if (!secret || !storefrontToken() || !(await draftMode()).isEnabled) {
+    return null;
+  }
+  const token = (await cookies()).get(THEME_PREVIEW_COOKIE)?.value ?? null;
+  return (await verifyThemePreview(secret, token)) ? token : null;
+}

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

@@ -12,8 +12,9 @@ Every storefront — hand-written or generated — imports the SDK **only** thro
 | `@magicstoreai/storefront-client` | `createStorefrontClient`: one typed method per API `operationId`, `MagicStoreError`, `paginate`, `Schema<>` | anywhere, no React      |
 | `@magicstoreai/hydrogen`          | React: `MagicStoreProvider`, `useCart`, `useCustomer`, `useWishlist`, `<Money>`, `<Image>`, …               | client (`"use client"`) |
 | `@magicstoreai/hydrogen/core`     | The same state without React: `CartController`, `CustomerSessionController`, `formatMoney`, variants, blog | anywhere                |
-| `@magicstoreai/hydrogen/server`   | `nextCacheFetch` (cache tags), `createWebhookHandler` (signed webhooks → revalidation)                      | server, edge            |
+| `@magicstoreai/hydrogen/server`   | `nextCacheFetch` (cache tags), `createWebhookHandler`, `loadTemplate`, `loadThemeSettings`, `verifyThemePreview` | server, edge            |
 | `@magicstoreai/hydrogen/seo`      | `pageMeta`, `productJsonLd`, `articleMeta`, `articleJsonLd`, `breadcrumbJsonLd`, `jsonLdScript`              | anywhere                |
+| `@magicstoreai/hydrogen/theme`    | Themes: `defineSection`, `defineBlock`, `defineTheme`, `ThemeSections`, `validateTemplate`, `resolveTemplate` | anywhere                |
 
 Never import from `src/` or `dist/` of a package, and never call `/api/v2/storefront/…` by URL —
 call the client method. A server component takes only components (`<Image>`, `<Money>`, …) from
@@ -100,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
@@ -141,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`.
 
@@ -178,6 +192,144 @@ The SDK does not validate `initData` (the server does), does not parse referrals
 (the server attributes them), and never sends `responseUnsafe`. Never put `initData` in a URL, a log
 or analytics.
 
+## Themes
+
+A storefront is a **theme** (Shopify Online Store 2.0 style): its pages are templates
+(`theme/templates/index.json` for the home, `page.json` for content pages) made of sections the
+merchant reorders and edits in the admin's theme editor. `create-magic-storefront theme push` (a
+`mtt_` theme deploy token, server-side only, never in a browser) sends the manifest; pages read the
+merchant's version with `loadTemplate(api, 'index', theme)` and render it with `ThemeSections`. Until
+a theme is pushed, the bundled templates render. Webhooks `THEME_UPDATED` / `TEMPLATE_UPDATED`
+revalidate `magicstore:theme` / `magicstore:template:<name>`. The editor's preview opens
+`/api/magicstore/preview?token=…`, verified with `verifyThemePreview` (the webhook secret). Guide:
+`docs/themes.md` in the SDK repository.
+
+## Creating a new section
+
+Invent any section the design needs (`size-guide`, `lookbook`, `faq`): the backend has no code per
+section, so a section type it has never seen is fine — its schema arrives with `theme push`, and the
+editor, the validation and the merchant's AI tools work for it at once. A **setting type** it has
+never seen is not: compose the types below and never invent one; a missing type is a contract change
+in magicbot, made there first. `GET /home` is optional — data sections fetch through the catalog
+operations.
+
+1. Create `theme/sections/<type>.tsx` with `defineSection` and the component
+   (`SectionProps<typeof section>` types its `settings` and `blocks`).
+2. Register it in `theme/index.ts`: `sections` of `defineTheme` and the `components` map.
+3. Put it in a template (`theme/templates/*.json`) or give it `presets`, so the merchant can add it.
+4. Every word the buyer sees comes from a setting with a default in every locale (`en`, `ru`, `uz`).
+   No copy written into the component.
+5. Run `create-magic-storefront theme check` (must pass), then `theme push`, bumping the theme's
+   `version`; `theme dev` pushes on every change while developing.
+
+| Type              | Extra members                           | The component receives                                    |
+| ----------------- | --------------------------------------- | --------------------------------------------------------- |
+| `TEXT`            | `maxLength` (≤ 500)                     | `string`                                                  |
+| `TEXTAREA`        | `maxLength` (≤ 5 000)                   | `string`                                                  |
+| `RICHTEXT`        | —                                       | sanitised HTML `string` (the only HTML a section renders) |
+| `URL`             | —                                       | `string \| null`                                          |
+| `COLOR`           | —                                       | `#rrggbb` or `null`                                       |
+| `CHECKBOX`        | —                                       | `boolean`                                                 |
+| `NUMBER`          | `min`, `max` (optional)                 | `number \| null`                                          |
+| `RANGE`           | `min`, `max`, `step`, `unit` (optional) | `number`                                                  |
+| `SELECT`          | `options: [{ value, label }]` (≤ 100)   | one option `value`                                        |
+| `IMAGE`           | —                                       | `{ url, altText: null, width, height }` or `null`         |
+| `COLLECTION`      | —                                       | `{ id, handle, title }` or `null`                         |
+| `PRODUCT`         | —                                       | `{ id, handle, title }` or `null`                         |
+| `COLLECTION_LIST` | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `PRODUCT_LIST`    | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `HEADER`          | `content` (no `id`)                     | — (a heading in the editor form)                          |
+| `PARAGRAPH`       | `content` (no `id`)                     | — (a note in the editor form)                             |
+
+Ids are camelCase; `SELECT` values are `UPPER_SNAKE_CASE`. Text is stored per locale and served in
+the request's. References (`IMAGE`, `COLLECTION`, `PRODUCT`, lists) default to empty and are not full
+products — fetch what you show by `handle`. Blocks (`defineBlock`) are repeatable children: slides,
+quotes, table rows.
+
+Worked example, `theme/sections/size-guide.tsx` (a heading and a table of `row` blocks):
+
+```tsx
+import { defineBlock, defineSection, type SectionProps } from '@magicstoreai/hydrogen/theme';
+
+import { label } from '../text';
+
+const row = defineBlock({
+  type: 'row',
+  name: label('Size', 'Размер', "O'lcham"),
+  settings: [
+    { id: 'size', type: 'TEXT', label: label('Size', 'Размер', "O'lcham"), default: '' },
+    { id: 'chest', type: 'TEXT', label: label('Chest', 'Грудь', "Ko'krak"), default: '' },
+    { id: 'waist', type: 'TEXT', label: label('Waist', 'Талия', 'Bel'), default: '' },
+  ],
+});
+
+export const sizeGuide = defineSection({
+  type: 'size-guide',
+  name: label('Size guide', 'Таблица размеров', "O'lchamlar jadvali"),
+  maxBlocks: 30,
+  settings: [
+    {
+      id: 'heading',
+      type: 'TEXT',
+      label: label('Heading', 'Заголовок', 'Sarlavha'),
+      default: { en: 'Size guide', ru: 'Таблица размеров', uz: "O'lchamlar jadvali" },
+    },
+    {
+      id: 'columns',
+      type: 'TEXT',
+      label: label('Column names', 'Названия колонок', 'Ustun nomlari'),
+      info: label('Separated by commas.', 'Через запятую.', 'Vergul bilan.'),
+      default: {
+        en: 'Size, Chest cm, Waist cm',
+        ru: 'Размер, Грудь см, Талия см',
+        uz: "O'lcham, Ko'krak sm, Bel sm",
+      },
+    },
+  ],
+  blocks: [row],
+  presets: [
+    {
+      name: label('Size guide', 'Таблица размеров', "O'lchamlar jadvali"),
+      blocks: [{ type: 'row' }, { type: 'row' }, { type: 'row' }],
+    },
+  ],
+});
+
+/** A size table the merchant fills row by row; nothing shows until a row has a size. */
+export function SizeGuide({ settings, blocks }: SectionProps<typeof sizeGuide>) {
+  const rows = blocks.filter((block) => block.settings.size !== '');
+  if (rows.length === 0) {
+    return null;
+  }
+  return (
+    <section className="stack">
+      <h2>{settings.heading}</h2>
+      <table>
+        <thead>
+          <tr>
+            {settings.columns.split(',').map((name) => (
+              <th key={name}>{name.trim()}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map(({ id, settings: cells }) => (
+            <tr key={id}>
+              <td>{cells.size}</td>
+              <td>{cells.chest}</td>
+              <td>{cells.waist}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+```
+
+Register it (`sizeGuide` in `sections`, `'size-guide': SizeGuide` in `components`), then
+`theme check` and `theme push`.
+
 ## What the SDK does not do
 
 - Compute or round prices, discounts, taxes, delivery fees or stock — the API returns them.

package/template/package.json

@@ -4,10 +4,12 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "next dev",
-    "build": "next build",
+    "dev": "node scripts/theme.mjs dev",
+    "build": "node scripts/theme.mjs prebuild && next build",
     "start": "next start",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "theme:check": "create-magic-storefront theme check",
+    "theme:push": "create-magic-storefront theme push"
   },
   "dependencies": {
     "@magicstoreai/hydrogen": "workspace:*",
@@ -22,6 +24,7 @@
     "@types/node": "^26.6.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
+    "create-magic-storefront": "workspace:*",
     "jsdom": "^30.1.1",
     "typescript": "5.9.3"
   }

package/template/scripts/theme.mjs

@@ -0,0 +1,53 @@
+// Keeps the theme the admin edits in step with this code.
+//
+//   node scripts/theme.mjs dev       next dev, plus `theme dev` (push to DEVELOPMENT on every change
+//                                    under theme/) when MAGICSTORE_THEME_TOKEN is set
+//   node scripts/theme.mjs prebuild  (before `next build`) `theme check`, plus `theme push --publish` when
+//                                    MAGICSTORE_THEME_PUBLISH=1, so a deployed storefront never
+//                                    renders a section the backend does not know
+//
+// MAGICSTORE_THEME_TOKEN is the theme deploy token (mtt_…): server-side only, never NEXT_PUBLIC_.
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+for (const file of ['.env.local', '.env']) {
+  if (existsSync(file)) {
+    process.loadEnvFile(file);
+  }
+}
+
+const require = createRequire(import.meta.url);
+const cliPackage = require.resolve('create-magic-storefront/package.json');
+const cli = join(dirname(cliPackage), require(cliPackage).bin['create-magic-storefront']);
+
+function run(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: 'inherit' });
+    child.on('exit', (code) => resolve(code ?? 1));
+  });
+}
+
+const theme = (...args) => run(process.execPath, [cli, 'theme', ...args]);
+const mode = process.argv[2];
+
+if (mode === 'dev') {
+  const next = run(process.execPath, [require.resolve('next/dist/bin/next'), 'dev']);
+  if (process.env.MAGICSTORE_THEME_TOKEN) {
+    theme('dev');
+  }
+  process.exit(await next);
+} else if (mode === 'prebuild') {
+  const checked = await theme('check');
+  if (checked !== 0) {
+    process.exit(checked);
+  }
+  if (process.env.MAGICSTORE_THEME_PUBLISH === '1') {
+    process.exit(await theme('push', '--publish'));
+  }
+} else {
+  console.error('Usage: node scripts/theme.mjs dev|prebuild');
+  process.exit(1);
+}