create-magic-storefront 0.2.0 → 0.4.0

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/errors.ts

@@ -5,3 +5,24 @@ import { MagicStoreError } from '@magicstoreai/storefront-client';
 export function describe(error: unknown, fallback: string): string {
   return error instanceof MagicStoreError ? (error.detail ?? error.message) : fallback;
 }
+
+/**
+ * Why sharing the Telegram phone (`POST /customer/phone-verification`) failed. `CONTACT_EXPIRED`
+ * asks to share again; `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE` and `TAKEN` show the
+ * API's localized message for `telegramContact`; anything else falls back to `describe()`.
+ */
+export function describePhoneShare(
+  error: unknown,
+  text: { sharePhoneAgain: string; tryAgainLater: string },
+): string {
+  if (error instanceof MagicStoreError) {
+    const refusal = error.errors.find((entry) => entry.field === 'telegramContact');
+    if (refusal?.code === 'CONTACT_EXPIRED') {
+      return text.sharePhoneAgain;
+    }
+    if (refusal !== undefined) {
+      return refusal.message;
+    }
+  }
+  return describe(error, text.tryAgainLater);
+}

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',
@@ -117,6 +119,16 @@ const en = {
   signIn: 'Sign in',
   sendCode: 'Send code',
   smsCode: 'Code from the SMS',
+  // Telegram Mini App
+  signInWithTelegram: 'Sign in with Telegram',
+  signingIn: 'Signing in…',
+  telegramRelaunch:
+    'Your Telegram sign-in has expired. Close the shop and open it again from the bot.',
+  telegramUnavailable: 'Sign-in with Telegram is not available in this shop.',
+  orWithPhone: 'Or sign in with your phone number',
+  sharePhone: 'Share phone number',
+  sharePhoneHint: 'Share your Telegram phone number so the shop can reach you about orders.',
+  sharePhoneAgain: 'That contact has expired. Share it again.',
   signOut: 'Sign out',
   orders: 'Orders',
   loadingOrders: 'Loading orders…',
@@ -172,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: 'Выбор редакции',
@@ -227,6 +241,14 @@ const ru: Messages = {
   signIn: 'Войти',
   sendCode: 'Получить код',
   smsCode: 'Код из SMS',
+  signInWithTelegram: 'Войти через Telegram',
+  signingIn: 'Входим…',
+  telegramRelaunch: 'Вход через Telegram устарел. Закройте магазин и откройте его снова из бота.',
+  telegramUnavailable: 'Вход через Telegram в этом магазине недоступен.',
+  orWithPhone: 'Или войдите по номеру телефона',
+  sharePhone: 'Поделиться номером',
+  sharePhoneHint: 'Поделитесь номером из Telegram, чтобы магазин мог связаться с вами по заказам.',
+  sharePhoneAgain: 'Контакт устарел. Поделитесь им ещё раз.',
   signOut: 'Выйти',
   orders: 'Заказы',
   loadingOrders: 'Загружаем заказы…',
@@ -279,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',
@@ -334,6 +358,15 @@ const uz: Messages = {
   signIn: 'Kirish',
   sendCode: 'Kod olish',
   smsCode: 'SMS dagi kod',
+  signInWithTelegram: 'Telegram orqali kirish',
+  signingIn: 'Kirilmoqda…',
+  telegramRelaunch: "Telegram orqali kirish eskirdi. Do'konni yoping va botdan qayta oching.",
+  telegramUnavailable: "Bu do'konda Telegram orqali kirish mavjud emas.",
+  orWithPhone: 'Yoki telefon raqami bilan kiring',
+  sharePhone: 'Raqamni ulashish',
+  sharePhoneHint:
+    "Do'kon buyurtmalar bo'yicha bog'lana olishi uchun Telegram raqamingizni ulashing.",
+  sharePhoneAgain: 'Kontakt eskirdi. Uni qayta ulashing.',
   signOut: 'Chiqish',
   orders: 'Buyurtmalar',
   loadingOrders: 'Buyurtmalar yuklanmoqda…',

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/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
@@ -54,7 +55,7 @@ product, search, blog, cart, checkout, sign-in, orders, SEO, webhook revalidatio
   any other origin the API answers `ORIGIN_NOT_ALLOWED`. Without a token for the browser, proxy
   browser calls through your own server (the starter's `app/storefront-api/[...path]`).
 - **Which customer** — a customer session: access token (60 min) + refresh token (30 days,
-  single-use), only on customer routes. `useCustomer()` signs in (OTP, Telegram, OQ, Click),
+  single-use), only on customer routes. `useCustomer()` signs in (OTP, Telegram, phone-only, OQ, Click),
   refreshes and signs out; `MagicStoreProvider` keeps the session in storage.
 
 Public catalog reads need no customer. Render them on the server with a client whose `fetch` is
@@ -144,6 +145,178 @@ for buyers), quote `error.requestId` when reporting. GET calls retry on 429 / 5x
 
 The full list, with the `meta` each code carries, is in the backend's `docs/api/v2/standards.md`.
 
+## Telegram Mini App
+
+The same storefront runs inside Telegram as a Mini App (`shop.features.telegramBot` says the shop has
+a bot). The app loads `TELEGRAM_WEB_APP_SCRIPT` (from `@magicstoreai/hydrogen/core`) in the document
+head; the SDK never injects it.
+
+- `useTelegramWebApp({ documentAttributes: true })`: `status` is `unknown` on the server and the first
+  client render, then `telegram` or `browser` (a Mini App = `window.Telegram.WebApp` with a non-empty
+  `initData`). Marks `<html data-telegram data-color-scheme>`; map Telegram's `--tg-theme-*` CSS
+  variables onto your tokens under `html[data-telegram]`.
+- `useTelegramSignIn()`: signs in once per provider with `initData` (`POST /auth/telegram`) when
+  opened from the bot, unless the stored session was signed in as that same Telegram user (any other
+  session is signed out first). `failed` + `UNAUTHENTICATED` → "reopen the shop from the bot";
+  `FORBIDDEN` → the shop has no bot. `status` / `error` are shared under one provider, so an
+  `{ auto: false }` page shows the automatic attempt's progress and failure.
+- `useTelegramBackButton(visible, onBack)`, `useTelegramMainButton(options | null)`: one button per
+  page, registrations stack (the latest owns it); MainButton changes apply in place.
+- `useCustomer().shareTelegramPhone()`: `requestContact` → `POST /customer/phone-verification` with
+  the signed `response`; `null` when declined; rejects `UNAUTHENTICATED` at once when nobody is
+  signed in (show the button to signed-in customers only, and only while
+  `useTelegramWebApp().canRequestContact` — older clients resolve `null` without asking). Refusals: `VALIDATION_FAILED` with `CONTACT_EXPIRED`
+  (share again), `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE`, `TAKEN` on `telegramContact`.
+- `useCustomer().signInWithPhone(phone)`: only when `shop.features.otpLogin === false`.
+
+- `useCustomer().verifyPhoneWithTelegram(telegramContact)`: the same proof with a contact the app
+  got itself. `/core`: `TelegramWebAppController.mainButton(options)` → `{ update, release }`.
+- Call `useTelegramSignIn()` with `auto` in exactly one app-wide component; anywhere else
+  `{ auto: false }` + `signIn()`. Load the script only when `shop.features.telegramBot` is on. Starter
+  reference: `examples/starter/PAGES.md` → "Running as a Telegram Mini App".
+
+The SDK does not validate `initData` (the server does), does not parse referrals out of `startapp`
+(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:*",
@@ -18,9 +20,12 @@
     "server-only": "^0.0.1"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.3",
     "@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);
+}

package/template/theme/index.ts

@@ -0,0 +1,53 @@
+import { defineTheme, type SectionComponents } from '@magicstoreai/hydrogen/theme';
+
+import { CollectionList, collectionList } from './sections/collection-list';
+import { FeaturedCollection, featuredCollection } from './sections/featured-collection';
+import { Hero, hero } from './sections/hero';
+import { ImageWithText, imageWithText } from './sections/image-with-text';
+import { pageContent } from './sections/page-content';
+import { PlatformHome, platformHome } from './sections/platform-home';
+import { ProductShelf, productShelf } from './sections/product-shelf';
+import { RichText, richText } from './sections/rich-text';
+import { Testimonials, testimonials } from './sections/testimonials';
+import { settings } from './settings';
+import index from './templates/index.json';
+import page from './templates/page.json';
+
+/**
+ * The storefront's theme: what `create-magic-storefront theme push` sends, so the merchant edits
+ * these sections in the admin. A new section is registered here and in `components`, then pushed
+ * (`PAGES.md`, "Creating a new section"). Bump `version` with every push of a changed theme.
+ */
+const theme = defineTheme({
+  name: 'starter',
+  version: '1.0.0',
+  sections: [
+    hero,
+    richText,
+    imageWithText,
+    featuredCollection,
+    collectionList,
+    testimonials,
+    productShelf,
+    pageContent,
+    platformHome,
+  ],
+  settings,
+  templates: { index, page },
+});
+
+export default theme;
+
+/**
+ * One component per section type. `page-content` is bound to the page by `app/pages/[handle]`.
+ */
+export const components: SectionComponents<typeof theme.sections> = {
+  hero: Hero,
+  'rich-text': RichText,
+  'image-with-text': ImageWithText,
+  'featured-collection': FeaturedCollection,
+  'collection-list': CollectionList,
+  testimonials: Testimonials,
+  'product-shelf': ProductShelf,
+  'platform-home': PlatformHome,
+};

package/template/theme/sections/collection-list.tsx

@@ -0,0 +1,64 @@
+import { MagicStoreError } from '@magicstoreai/storefront-client';
+import { defineBlock, defineSection, type SectionProps } from '@magicstoreai/hydrogen/theme';
+
+import { CollectionTiles } from '@/components/sections/collections';
+import { api } from '@/lib/api';
+
+import { label } from '../text';
+
+export const collectionBlock = defineBlock({
+  type: 'collection',
+  name: label('Collection', 'Коллекция', "To'plam"),
+  settings: [
+    { id: 'collection', type: 'COLLECTION', label: label('Collection', 'Коллекция', "To'plam") },
+  ],
+});
+
+export const collectionList = defineSection({
+  type: 'collection-list',
+  name: label('Collections', 'Коллекции', "To'plamlar"),
+  icon: 'COLLECTIONS',
+  category: 'COLLECTIONS',
+  maxBlocks: 8,
+  settings: [
+    { id: 'heading', type: 'TEXT', label: label('Heading', 'Заголовок', 'Sarlavha'), default: '' },
+  ],
+  blocks: [collectionBlock],
+  presets: [
+    {
+      name: label('Collections', 'Коллекции', "To'plamlar"),
+      blocks: [{ type: 'collection' }, { type: 'collection' }, { type: 'collection' }],
+    },
+  ],
+});
+
+/** Tiles of the collections the merchant picked, in their order. */
+export async function CollectionList({ settings, blocks }: SectionProps<typeof collectionList>) {
+  const handles = blocks.flatMap((block) =>
+    block.settings.collection ? [block.settings.collection.handle] : [],
+  );
+  const collections = await Promise.all(
+    handles.map((handle) =>
+      api.collectionsShow({ path: { handle } }).then(
+        ({ data }) => data,
+        (error: unknown) => {
+          // Unpublished between the template read and this one: leave the tile out.
+          if (error instanceof MagicStoreError && error.code === 'NOT_FOUND') {
+            return null;
+          }
+          throw error;
+        },
+      ),
+    ),
+  );
+  const found = collections.filter((collection) => collection !== null);
+  if (found.length === 0) {
+    return null;
+  }
+  return (
+    <section className="stack">
+      {settings.heading && <h2>{settings.heading}</h2>}
+      <CollectionTiles collections={found} />
+    </section>
+  );
+}

package/template/theme/sections/featured-collection.tsx

@@ -0,0 +1,56 @@
+import { defineSection, type SectionProps } from '@magicstoreai/hydrogen/theme';
+
+import { Shelf } from '@/components/sections/product-shelves';
+import { api } from '@/lib/api';
+
+import { label } from '../text';
+
+export const featuredCollection = defineSection({
+  type: 'featured-collection',
+  name: label('Featured collection', 'Подборка из коллекции', "To'plamdan tanlov"),
+  icon: 'PRODUCTS',
+  category: 'PRODUCTS',
+  settings: [
+    { id: 'collection', type: 'COLLECTION', label: label('Collection', 'Коллекция', "To'plam") },
+    {
+      id: 'heading',
+      type: 'TEXT',
+      label: label('Heading', 'Заголовок', 'Sarlavha'),
+      info: label(
+        'Empty: the collection title.',
+        'Пусто — название коллекции.',
+        "Bo'sh — to'plam nomi.",
+      ),
+      default: '',
+    },
+    {
+      id: 'limit',
+      type: 'RANGE',
+      label: label('Products', 'Товаров', 'Mahsulotlar'),
+      min: 2,
+      max: 24,
+      step: 1,
+      default: 8,
+    },
+  ],
+  presets: [{ name: label('Featured collection', 'Подборка из коллекции', "To'plamdan tanlov") }],
+});
+
+/** Products of the collection the merchant picked; nothing until one is picked. */
+export async function FeaturedCollection({ settings }: SectionProps<typeof featuredCollection>) {
+  const { collection } = settings;
+  if (collection === null) {
+    return null;
+  }
+  const { data } = await api.collectionsProducts({
+    path: { handle: collection.handle },
+    query: { perPage: settings.limit },
+  });
+  return (
+    <Shelf
+      title={settings.heading || collection.title}
+      href={`/collections/${collection.handle}`}
+      products={data}
+    />
+  );
+}