create-magic-storefront 0.3.1 → 0.4.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/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/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
@@ -178,6 +179,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);
+}

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}
+    />
+  );
+}