create-magic-storefront 0.1.3 → 0.3.1

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

@@ -0,0 +1,136 @@
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import { Image } from '@magicstoreai/hydrogen';
+import { embeddedProductFilters, orderEmbeddedProducts } from '@magicstoreai/hydrogen/core';
+import {
+  articleJsonLd,
+  articleMeta,
+  breadcrumbJsonLd,
+  jsonLdScript,
+} from '@magicstoreai/hydrogen/seo';
+import { ArticleView } from '@/components/analytics-views';
+import { ArticleBody } from '@/components/article-body';
+import { ArticleDate, ArticleGrid } from '@/components/article-card';
+import { ArticleVote } from '@/components/article-vote';
+import { api, locale, orNotFound } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+import { siteOrigin } from '@/lib/site';
+
+type Props = { params: Promise<{ handle: string }> };
+
+/**
+ * An article is served only in the languages it is written in: in any other one the API answers
+ * 404, and so does this page.
+ */
+async function article(handle: string) {
+  return (await orNotFound(api.blogArticlesShow({ path: { handle } }))).data;
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { handle } = await params;
+  const [found, { data: shop }] = await Promise.all([article(handle), api.shop()]);
+  // A single-language storefront: no `urlForLocale`, so no hreflang alternates.
+  return articleMeta(found, { url: `${siteOrigin(shop)}/blog/${found.handle}`, shop });
+}
+
+export default async function ArticlePage({ params }: Props) {
+  const { handle } = await params;
+  const t = messages(locale);
+  const [found, { data: shop }] = await Promise.all([article(handle), api.shop()]);
+  // Prices and stock of the embedded products come live from /products, in one call (rarely two);
+  // that list has its own order, so put it back in the article's.
+  const [related, ...productPages] = await Promise.all([
+    api.blogArticlesRelated({ path: { handle }, query: { perPage: 3 } }),
+    ...embeddedProductFilters(found.products).map((handles) =>
+      api.productsIndex({ query: { 'filter[handles]': handles, perPage: 100 } }),
+    ),
+  ]);
+  const products = orderEmbeddedProducts(
+    found.products,
+    productPages.flatMap((result) => result.data),
+  );
+  const url = `${siteOrigin(shop)}/blog/${found.handle}`;
+  const blogTitle = shop.blog?.title || t.blog;
+
+  return (
+    <article className="stack article">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript(articleJsonLd(found, { url, shop, locale })),
+        }}
+      />
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript(
+            breadcrumbJsonLd([
+              { name: t.home, url: '/' },
+              { name: blogTitle, url: '/blog' },
+              ...(found.category
+                ? [{ name: found.category.title, url: `/blog/category/${found.category.handle}` }]
+                : []),
+              { name: found.title, url: `/blog/${found.handle}` },
+            ]),
+          ),
+        }}
+      />
+      <ArticleView articleId={found.id} />
+      <nav className="row muted" aria-label={blogTitle}>
+        <Link href="/blog">{blogTitle}</Link>
+        {found.category && (
+          <>
+            <span aria-hidden="true">/</span>
+            <Link href={`/blog/category/${found.category.handle}`}>{found.category.title}</Link>
+          </>
+        )}
+      </nav>
+      <h1>{found.h1 ?? found.title}</h1>
+      <p className="row muted">
+        {found.author ? (
+          <Link href={`/blog/author/${found.author.handle}`}>{found.authorName}</Link>
+        ) : (
+          found.authorName && <span>{found.authorName}</span>
+        )}
+        <ArticleDate iso={found.publishedAt} timeZone={shop.timezone} />
+        <span>{t.readingTime(found.readingMinutes)}</span>
+      </p>
+      {/* The cover is the page's largest image: loaded at once, not lazily. */}
+      <Image data={found.image} alt={found.title} loading="eager" className="article-cover" />
+      <div className="prose">
+        <ArticleBody
+          bodyHtml={found.bodyHtml}
+          products={new Map(products.map((product) => [product.handle, product]))}
+        />
+      </div>
+      {found.tags.length > 0 && (
+        <nav className="row chips" aria-label={t.tag}>
+          {found.tags.map((tag) => (
+            <Link key={tag.handle} href={`/blog/tag/${tag.handle}`}>
+              #{tag.title}
+            </Link>
+          ))}
+        </nav>
+      )}
+      {found.author && (
+        <aside className="row author">
+          <Image data={found.author.avatar} alt={found.author.name} width={64} height={64} />
+          <div className="stack">
+            <Link href={`/blog/author/${found.author.handle}`}>
+              <strong>{found.author.name}</strong>
+            </Link>
+            {found.author.role && <span className="muted">{found.author.role}</span>}
+            {found.authorBio && <p>{found.authorBio}</p>}
+          </div>
+        </aside>
+      )}
+      <ArticleVote handle={found.handle} helpfulCount={found.helpfulCount} />
+      {related.data.length > 0 && (
+        <section className="stack">
+          <h2>{t.relatedArticles}</h2>
+          <ArticleGrid articles={related.data} timeZone={shop.timezone} />
+        </section>
+      )}
+    </article>
+  );
+}

package/template/app/blog/author/[handle]/page.tsx

@@ -0,0 +1,44 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { Image } from '@magicstoreai/hydrogen';
+import { pageMeta } from '@magicstoreai/hydrogen/seo';
+import { ArticleListing, pageParam } from '@/components/blog-listing';
+import { api } from '@/lib/api';
+
+type Props = { params: Promise<{ handle: string }>; searchParams: Promise<{ page?: string }> };
+
+/** The author, or 404: the list holds only authors with an article in this language. */
+async function author(handle: string) {
+  const { data } = await api.blogAuthorsIndex();
+  return data.find((item) => item.handle === handle) ?? notFound();
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { handle } = await params;
+  const [found, { data: shop }] = await Promise.all([author(handle), api.shop()]);
+  const meta = pageMeta({ title: found.name, description: found.role, shop });
+  return { title: meta.title, description: meta.description };
+}
+
+export default async function BlogAuthorPage({ params, searchParams }: Props) {
+  const { handle } = await params;
+  const page = pageParam((await searchParams).page);
+  const [found, { data: shop }] = await Promise.all([author(handle), api.shop()]);
+
+  return (
+    <div className="stack">
+      <header className="row author">
+        <Image data={found.avatar} alt={found.name} width={64} height={64} />
+        <div>
+          <h1>{found.name}</h1>
+          {found.role && <p className="muted">{found.role}</p>}
+        </div>
+      </header>
+      <ArticleListing
+        query={{ page, 'filter[author]': handle }}
+        href={(p) => `/blog/author/${handle}${p > 1 ? `?page=${p}` : ''}`}
+        timeZone={shop.timezone}
+      />
+    </div>
+  );
+}

package/template/app/blog/category/[handle]/page.tsx

@@ -0,0 +1,52 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { breadcrumbJsonLd, jsonLdScript, pageMeta } from '@magicstoreai/hydrogen/seo';
+import { ArticleListing, CategoryNav, pageParam } from '@/components/blog-listing';
+import { api, locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Props = { params: Promise<{ handle: string }>; searchParams: Promise<{ page?: string }> };
+
+/** The category, or 404: the list holds only categories with an article in this language. */
+async function category(handle: string) {
+  const { data } = await api.blogCategoriesIndex();
+  return data.find((item) => item.handle === handle) ?? notFound();
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { handle } = await params;
+  const [found, { data: shop }] = await Promise.all([category(handle), api.shop()]);
+  const meta = pageMeta({ title: found.title, shop });
+  return { title: meta.title };
+}
+
+export default async function BlogCategoryPage({ params, searchParams }: Props) {
+  const { handle } = await params;
+  const page = pageParam((await searchParams).page);
+  const t = messages(locale);
+  const [found, { data: shop }] = await Promise.all([category(handle), api.shop()]);
+
+  return (
+    <div className="stack">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript(
+            breadcrumbJsonLd([
+              { name: t.home, url: '/' },
+              { name: shop.blog?.title || t.blog, url: '/blog' },
+              { name: found.title, url: `/blog/category/${handle}` },
+            ]),
+          ),
+        }}
+      />
+      <h1>{found.title}</h1>
+      <CategoryNav current={handle} />
+      <ArticleListing
+        query={{ page, 'filter[category]': handle }}
+        href={(p) => `/blog/category/${handle}${p > 1 ? `?page=${p}` : ''}`}
+        timeZone={shop.timezone}
+      />
+    </div>
+  );
+}

package/template/app/blog/page.tsx

@@ -0,0 +1,97 @@
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import { breadcrumbJsonLd, jsonLdScript, pageMeta } from '@magicstoreai/hydrogen/seo';
+import { ArticleGrid } from '@/components/article-card';
+import { ArticleListing, CategoryNav, pageParam, sortParam } from '@/components/blog-listing';
+import { api, locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Props = { searchParams: Promise<{ q?: string; sort?: string; page?: string }> };
+
+export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
+  const { data: shop } = await api.shop();
+  const { q, sort } = await searchParams;
+  const meta = pageMeta({
+    title: shop.blog?.title || messages(locale).blog,
+    description: shop.blog?.description ?? null,
+    shop,
+  });
+  return {
+    title: meta.title,
+    description: meta.description,
+    // Search results are endless and a sort repeats the same articles: keep both out of the index.
+    ...((q || sort) && { robots: { index: false, follow: true } }),
+  };
+}
+
+/** The blog home: the merchant's heading, categories, editor's picks, then every article. */
+export default async function BlogPage({ searchParams }: Props) {
+  const { q = '', sort: sortValue, page: pageValue } = await searchParams;
+  const sort = sortParam(sortValue);
+  const page = pageParam(pageValue);
+  const t = messages(locale);
+  const { data: shop } = await api.shop();
+  const showFeatured = page === 1 && !q && !sort;
+  const featured = showFeatured
+    ? (await api.blogArticlesIndex({ query: { 'filter[featured]': 'true', perPage: 3 } })).data
+    : [];
+  const href = (p: number) => {
+    const params = new URLSearchParams({
+      ...(q && { q }),
+      ...(sort && { sort }),
+      ...(p > 1 && { page: String(p) }),
+    });
+    return params.size > 0 ? `/blog?${params}` : '/blog';
+  };
+
+  return (
+    <div className="stack">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript(
+            breadcrumbJsonLd([
+              { name: t.home, url: '/' },
+              { name: shop.blog?.title || t.blog, url: '/blog' },
+            ]),
+          ),
+        }}
+      />
+      <h1>{shop.blog?.title || t.blog}</h1>
+      {shop.blog?.description && <p className="muted">{shop.blog.description}</p>}
+      <CategoryNav />
+      <form className="row" action="/blog">
+        <input name="q" defaultValue={q} placeholder={t.searchArticles} maxLength={200} />
+        <button className="primary">{t.search}</button>
+      </form>
+      <nav className="row chips" aria-label={t.sortNewest}>
+        <Link
+          href={q ? `/blog?q=${encodeURIComponent(q)}` : '/blog'}
+          aria-current={!sort ? 'page' : undefined}
+        >
+          {t.sortNewest}
+        </Link>
+        <Link
+          href={`/blog?${new URLSearchParams({ ...(q && { q }), sort: '-recentViews' })}`}
+          aria-current={sort === '-recentViews' ? 'page' : undefined}
+        >
+          {t.sortPopular}
+        </Link>
+      </nav>
+      {featured.length > 0 && (
+        <section className="stack">
+          <h2>{t.featured}</h2>
+          <ArticleGrid articles={featured} timeZone={shop.timezone} />
+        </section>
+      )}
+      {/* The picks are not repeated below; a blog of only picks shows no second list. */}
+      <ArticleListing
+        query={{ page, ...(q && { q }), ...(sort && { sort }) }}
+        exclude={featured.map((article) => article.id)}
+        {...(featured.length > 0 && { heading: t.allArticles })}
+        href={href}
+        timeZone={shop.timezone}
+      />
+    </div>
+  );
+}

package/template/app/blog/tag/[handle]/page.tsx

@@ -0,0 +1,51 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { ArticleGrid } from '@/components/article-card';
+import { ARTICLES_PER_PAGE, pageParam } from '@/components/blog-listing';
+import { Pager } from '@/components/pager';
+import { api, locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Props = { params: Promise<{ handle: string }>; searchParams: Promise<{ page?: string }> };
+
+/**
+ * Articles with a tag. There is no tag list in the API: the tag's title comes from its articles,
+ * and a tag without any (in this language) is a 404.
+ */
+async function tagged(handle: string, page: number) {
+  const articles = await api.blogArticlesIndex({
+    query: { page, perPage: ARTICLES_PER_PAGE, 'filter[tag]': handle },
+  });
+  if (articles.data.length === 0) {
+    notFound();
+  }
+  const detail = await api.blogArticlesShow({ path: { handle: articles.data[0]!.handle } });
+  const title = detail.data.tags.find((tag) => tag.handle === handle)?.title ?? handle;
+  return { articles, title };
+}
+
+export async function generateMetadata({ params, searchParams }: Props): Promise<Metadata> {
+  const { handle } = await params;
+  const { title } = await tagged(handle, pageParam((await searchParams).page));
+  return { title: `${messages(locale).tag}: ${title}`, robots: { index: false, follow: true } };
+}
+
+export default async function BlogTagPage({ params, searchParams }: Props) {
+  const { handle } = await params;
+  const page = pageParam((await searchParams).page);
+  const [{ articles, title }, { data: shop }] = await Promise.all([
+    tagged(handle, page),
+    api.shop(),
+  ]);
+
+  return (
+    <div className="stack">
+      <h1>#{title}</h1>
+      <ArticleGrid articles={articles.data} timeZone={shop.timezone} />
+      <Pager
+        meta={articles.meta.pagination}
+        href={(p) => `/blog/tag/${handle}${p > 1 ? `?page=${p}` : ''}`}
+      />
+    </div>
+  );
+}

package/template/app/globals.css

@@ -4,6 +4,9 @@
   --muted: #6b6b76;
   --line: #e7e7ec;
   --danger: #c62828;
+  /* Controls and image placeholders: white and light grey here, Telegram's colors in a Mini App. */
+  --surface: #fff;
+  --placeholder: #f3f3f6;
   /* Brand tokens: app/layout.tsx overrides them with the merchant's colors (lib/brand.ts). */
   --accent: #1f5eff;
   --on-accent: #fff;
@@ -20,6 +23,32 @@
   color: var(--fg);
   background: var(--bg);
 }
+/*
+ * Inside a Telegram Mini App (components/telegram-shell.tsx marks <html>): Telegram's theme, which
+ * its script writes as --tg-theme-* on <html>, with the defaults above as fallbacks. The merchant's
+ * accent from <html style> (lib/brand.ts) still wins over Telegram's button color.
+ */
+html[data-telegram] {
+  --bg: var(--tg-theme-bg-color, #fff);
+  --fg: var(--tg-theme-text-color, #16161a);
+  --muted: var(--tg-theme-hint-color, #6b6b76);
+  --danger: var(--tg-theme-destructive-text-color, #c62828);
+  --surface: var(--tg-theme-secondary-bg-color, #fff);
+  --placeholder: var(--tg-theme-secondary-bg-color, #f3f3f6);
+  --accent: var(--tg-theme-button-color, #1f5eff);
+  --on-accent: var(--tg-theme-button-text-color, #fff);
+}
+html[data-telegram][data-color-scheme='dark'] {
+  --line: rgba(255, 255, 255, 0.14);
+  color-scheme: dark;
+}
+html[data-telegram] body {
+  /* Telegram's stable viewport (the sheet can be dragged), the dynamic viewport outside it. */
+  min-height: var(--tg-viewport-stable-height, 100dvh);
+  padding-left: max(env(safe-area-inset-left), var(--tg-safe-area-inset-left, 0px));
+  padding-right: max(env(safe-area-inset-right), var(--tg-safe-area-inset-right, 0px));
+  padding-bottom: max(env(safe-area-inset-bottom), var(--tg-safe-area-inset-bottom, 0px));
+}
 * {
   box-sizing: border-box;
 }
@@ -72,9 +101,11 @@ header.site .brand img {
 .card img,
 .card .noimg {
   width: 100%;
+  /* The intrinsic width/height attributes (no layout shift) must not override the ratio. */
+  height: auto;
   aspect-ratio: 1;
   object-fit: cover;
-  background: #f3f3f6;
+  background: var(--placeholder);
   border-radius: 8px;
 }
 .muted {
@@ -115,7 +146,9 @@ button,
   padding: 10px 16px;
   border-radius: 8px;
   border: 1px solid var(--line);
-  background: #fff;
+  background: var(--surface);
+  color: var(--fg);
+  min-height: 44px;
   cursor: pointer;
   text-decoration: none;
 }
@@ -135,7 +168,10 @@ button:disabled {
 input,
 select {
   font: inherit;
+  min-height: 44px;
   padding: 9px 12px;
+  background: var(--surface);
+  color: var(--fg);
   border: 1px solid var(--line);
   border-radius: 8px;
 }
@@ -284,7 +320,7 @@ fieldset {
   width: 80px;
   height: 80px;
   object-fit: cover;
-  background: #f3f3f6;
+  background: var(--placeholder);
   border-radius: 12px;
 }
 .stories-circle .story img,
@@ -308,3 +344,69 @@ footer.site nav {
   gap: 16px;
   flex-wrap: wrap;
 }
+.articles {
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+}
+.article-card img,
+.article-card .noimg {
+  aspect-ratio: 16 / 9;
+}
+.article-card .badge {
+  align-self: flex-start;
+}
+.chips a {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  text-decoration: none;
+}
+.chips a[aria-current='page'] {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--on-accent);
+}
+.article {
+  max-width: 760px;
+  margin: 0 auto;
+}
+.article-cover {
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+.prose {
+  line-height: 1.65;
+}
+.prose img {
+  max-width: 100%;
+  height: auto;
+}
+.prose table {
+  display: block;
+  overflow-x: auto;
+}
+.article-product {
+  max-width: 260px;
+  margin: 16px 0;
+}
+.callout {
+  margin: 16px 0;
+  padding: 12px 16px;
+  border-left: 4px solid var(--accent);
+  border-radius: 8px;
+  background: var(--placeholder);
+}
+.callout[data-callout='warning'] {
+  border-left-color: var(--danger);
+}
+.author img {
+  border-radius: 50%;
+  object-fit: cover;
+}
+.author h1 {
+  margin: 0;
+}

package/template/app/layout.tsx

@@ -1,8 +1,12 @@
 import type { Metadata } from 'next';
 import Link from 'next/link';
+import Script from 'next/script';
 import type { ReactNode } from 'react';
 import { Image } from '@magicstoreai/hydrogen';
+// From /core, not the "use client" entry: a plain string a server component can read.
+import { TELEGRAM_WEB_APP_SCRIPT } from '@magicstoreai/hydrogen/core';
 import { CartLink } from '@/components/cart-link';
+import { TelegramShell } from '@/components/telegram-shell';
 import { api, locale } from '@/lib/api';
 import { brandStyle } from '@/lib/brand';
 import { messages } from '@/lib/i18n';
@@ -34,7 +38,12 @@ export default async function RootLayout({ children }: { children: ReactNode })
     // The merchant's colors, read per request: a change in the admin shows after SHOP_UPDATED.
     <html lang={locale} style={brandStyle(shop.branding)}>
       <body>
+        {/* Telegram's Mini App script, only for a shop with a bot: nobody else can open it in Telegram. */}
+        {shop.features.telegramBot && (
+          <Script src={TELEGRAM_WEB_APP_SCRIPT} strategy="beforeInteractive" />
+        )}
         <Providers shop={shop}>
+          <TelegramShell />
           <header className="site">
             <nav>
               <Link href="/" className="brand">
@@ -49,6 +58,8 @@ export default async function RootLayout({ children }: { children: ReactNode })
                   {collection.title}
                 </Link>
               ))}
+              {/* Only when an article is readable in this language (`features.blog`). */}
+              {shop.features.blog && <Link href="/blog">{t.blog}</Link>}
               <Link href="/search">{t.search}</Link>
               <Link href="/account">{t.account}</Link>
               <CartLink />

package/template/app/sitemap.ts

@@ -1,7 +1,15 @@
 import type { MetadataRoute } from 'next';
+import type { Schema } from '@magicstoreai/storefront-client';
 import { api } from '@/lib/api';
+import { siteOrigin } from '@/lib/site';
 
-const PATHS = { PAGE: 'pages', COLLECTION: 'collections', PRODUCT: 'products' } as const;
+/** URL prefix per `SitemapEntry.type`; a type added to the API later is skipped, not linked. */
+const PATHS: Partial<Record<string, string>> & Record<Schema<'SitemapEntry'>['type'], string> = {
+  PAGE: 'pages',
+  COLLECTION: 'collections',
+  PRODUCT: 'products',
+  ARTICLE: 'blog',
+};
 /** The sitemap protocol allows 50 000 URLs in one file: 50 pages of `GET /sitemap`. */
 const PER_PAGE = 1000;
 const MAX_PAGES = 50;
@@ -10,21 +18,23 @@ const MAX_PAGES = 50;
 export const dynamic = 'force-dynamic';
 
 /**
- * Every published product, collection and page (`GET /sitemap`, up to 1000 rows a page). URLs are
+ * Every published product, collection, page and blog article (`GET /sitemap`, up to 1000 rows a page). URLs are
  * absolute on `SITE_URL`, else the shop's primary domain.
  */
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const { data: shop } = await api.shop();
-  const origin =
-    process.env.SITE_URL?.replace(/\/+$/, '') ??
-    `https://${shop.primaryDomain ?? process.env.MAGICSTORE_SHOP_DOMAIN}`;
+  const origin = siteOrigin(shop);
 
   const entries: MetadataRoute.Sitemap = [{ url: `${origin}/` }];
   for (let page = 1; page <= MAX_PAGES; page++) {
     const { data, meta } = await api.sitemap({ query: { page, perPage: PER_PAGE } });
     for (const row of data) {
+      const prefix = PATHS[row.type];
+      if (!prefix) {
+        continue;
+      }
       entries.push({
-        url: `${origin}/${PATHS[row.type]}/${row.handle}`,
+        url: `${origin}/${prefix}/${row.handle}`,
         ...(row.updatedAt && { lastModified: row.updatedAt }),
       });
     }

package/template/components/analytics-views.tsx

@@ -16,3 +16,10 @@ export function SearchView({ query, resultsCount }: { query: string; resultsCoun
   useEffect(() => analytics.search(query, resultsCount), [analytics, query, resultsCount]);
   return null;
 }
+
+/** Reports an article read once per article (`ARTICLE_VIEW`); renders nothing. */
+export function ArticleView({ articleId }: { articleId: string }) {
+  const analytics = useAnalytics();
+  useEffect(() => analytics.articleView(articleId), [analytics, articleId]);
+  return null;
+}