create-brainerce-store 1.62.0 → 1.64.0

package/templates/nextjs/base/src/app/category/[slug]/page.tsx

@@ -1,7 +1,7 @@
 import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 import type { Product } from 'brainerce';
-import { getServerClient } from '@/core/lib/brainerce';
+import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
 import { buildMetaDescription } from '@/core/lib/seo';
 import { sanitizeHtml } from '@/core/lib/sanitize';
 import { decodeSlug } from '@/core/lib/utils';
@@ -26,17 +26,43 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { slug: rawSlug, locale } = await params;
   const slug = decodeSlug(rawSlug);
   try {
-    const category = await getServerClient(locale).getCategoryBySlug(slug);
+    const [category, storeInfo] = await Promise.all([
+      getServerClient(locale).getCategoryBySlug(slug),
+      fetchStoreInfo(locale),
+    ]);
     const description =
       category.metaDescription || buildMetaDescription(category.description) || category.name;
     const canonicalSlug = category.slug || slug;
     const canonicalPath = locale
       ? `/${locale}/category/${canonicalSlug}`
       : `/category/${canonicalSlug}`;
+
+    // hreflang: category URLs use the same slug across locales (only the
+    // locale prefix changes) — the same convention getCategorySitemapEntries
+    // emits, so the alternates always match real, crawlable URLs.
+    const supportedLocales = storeInfo?.i18n?.supportedLocales ?? [];
+    const defaultLoc = storeInfo?.i18n?.defaultLocale ?? storeInfo?.language ?? '';
+    const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || '';
+    const hreflangLanguages =
+      supportedLocales.length > 1
+        ? Object.fromEntries([
+            ...supportedLocales.map((loc) => [
+              loc,
+              loc === defaultLoc
+                ? `${baseUrl}/category/${canonicalSlug}`
+                : `${baseUrl}/${loc}/category/${canonicalSlug}`,
+            ]),
+            ['x-default', `${baseUrl}/category/${canonicalSlug}`],
+          ])
+        : undefined;
+
     return {
       title: category.name,
       description,
-      alternates: { canonical: canonicalPath },
+      alternates: {
+        canonical: canonicalPath,
+        ...(hreflangLanguages ? { languages: hreflangLanguages } : {}),
+      },
       openGraph: {
         title: category.name,
         description,

package/templates/nextjs/base/src/app/checkout/page.tsx

@@ -31,6 +31,7 @@ import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { useTranslations } from '@/core/lib/translations';
 import { cn } from '@/core/lib/utils';
 import { isValidCheckoutId } from '@/core/lib/safe-redirect';
+import { trackBeginCheckout } from '@/core/lib/tracking';
 
 type CheckoutStep = 'method' | 'address' | 'shipping' | 'pickup' | 'custom-fields' | 'payment';
 
@@ -69,6 +70,17 @@ function CheckoutContent() {
   const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
   const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
 
+  // `begin_checkout` — fired once the cart is loaded, guarded by a ref so a
+  // re-render (or the shopper returning from a canceled payment) doesn't
+  // report a second checkout start for the same cart.
+  const beganCheckoutForCartRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!cart?.id || !cart.items?.length) return;
+    if (beganCheckoutForCartRef.current === cart.id) return;
+    beganCheckoutForCartRef.current = cart.id;
+    trackBeginCheckout(cart, currency);
+  }, [cart, currency]);
+
   // Check for returning from canceled payment
   const canceled = searchParams.get('canceled') === 'true';
   const checkoutIdParam = searchParams.get('checkout_id');

package/templates/nextjs/base/src/app/contact/layout.tsx.ejs

@@ -0,0 +1,14 @@
+import type { Metadata } from 'next';
+
+// The contact page itself is a client component (the form is dashboard-
+// driven), so its metadata lives here. Indexable on purpose — a crawlable
+// contact page is a store-trust signal for both Google and AI assistants.
+export const metadata: Metadata = {
+  title: <%- language === 'he' ? "'צור קשר'" : "'Contact'" %>,
+  description: <%- language === 'he' ? "'יצירת קשר עם החנות — שאלות, הזמנות ושירות לקוחות.'" : "'Get in touch with the store — questions, orders, and support.'" %>,
+  alternates: { canonical: '/contact' },
+};
+
+export default function ContactLayout({ children }: { children: React.ReactNode }) {
+  return children;
+}

package/templates/nextjs/base/src/app/globals.css

@@ -1,36 +1,36 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 0 0% 9%;
-    --primary: 0 0% 9%;
-    --primary-foreground: 0 0% 98%;
-    --secondary: 0 0% 96%;
-    --secondary-foreground: 0 0% 9%;
-    --muted: 0 0% 96%;
-    --muted-foreground: 0 0% 45%;
-    --accent: 0 0% 96%;
-    --accent-foreground: 0 0% 9%;
-    --destructive: 0 84% 60%;
-    --destructive-foreground: 0 0% 98%;
-    --border: 0 0% 90%;
-    --input: 0 0% 90%;
-    --ring: 0 0% 9%;
-    --card: 0 0% 100%;
-    --card-foreground: 0 0% 9%;
-    --popover: 0 0% 100%;
-    --popover-foreground: 0 0% 9%;
-    --radius: 0.5rem;
-  }
-
-  * {
-    @apply border-border;
-  }
-
-  body {
-    @apply bg-background text-foreground antialiased;
-  }
-}
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 0 0% 9%;
+    --primary: 0 0% 9%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 0 0% 96%;
+    --secondary-foreground: 0 0% 9%;
+    --muted: 0 0% 96%;
+    --muted-foreground: 0 0% 45%;
+    --accent: 0 0% 96%;
+    --accent-foreground: 0 0% 9%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 0 0% 90%;
+    --input: 0 0% 90%;
+    --ring: 0 0% 9%;
+    --card: 0 0% 100%;
+    --card-foreground: 0 0% 9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 0 0% 9%;
+    --radius: 0.5rem;
+  }
+
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+  }
+}

package/templates/nextjs/base/src/app/indexnow-key.txt/route.ts

@@ -1,26 +1,26 @@
-/**
- * IndexNow key file — GET /indexnow-key.txt
- *
- * Brainerce's SEO Autopilot pings IndexNow (instant search-engine indexing)
- * whenever a blog post publishes. The ping includes
- * `keyLocation: https://<your-domain>/indexnow-key.txt`, and search engines
- * verify ownership by fetching this file and matching the key.
- *
- * The key comes from `getStoreInfo().seo.indexNowKey` — it is NOT a secret
- * (the file is public by protocol design). Returns 404 until the platform
- * generates a key for this sales channel, which is harmless.
- */
-import { getServerClient } from '@/core/lib/brainerce';
-
-export const revalidate = 3600;
-
-export async function GET() {
-  const info = await getServerClient()
-    .getStoreInfo()
-    .catch(() => null);
-  const key = info?.seo?.indexNowKey;
-  if (!key) return new Response(null, { status: 404 });
-  return new Response(key, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-}
+/**
+ * IndexNow key file — GET /indexnow-key.txt
+ *
+ * Brainerce's SEO Autopilot pings IndexNow (instant search-engine indexing)
+ * whenever a blog post publishes. The ping includes
+ * `keyLocation: https://<your-domain>/indexnow-key.txt`, and search engines
+ * verify ownership by fetching this file and matching the key.
+ *
+ * The key comes from `getStoreInfo().seo.indexNowKey` — it is NOT a secret
+ * (the file is public by protocol design). Returns 404 until the platform
+ * generates a key for this sales channel, which is harmless.
+ */
+import { getServerClient } from '@/core/lib/brainerce';
+
+export const revalidate = 3600;
+
+export async function GET() {
+  const info = await getServerClient()
+    .getStoreInfo()
+    .catch(() => null);
+  const key = info?.seo?.indexNowKey;
+  if (!key) return new Response(null, { status: 404 });
+  return new Response(key, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+}

package/templates/nextjs/base/src/app/layout.tsx.ejs

@@ -6,6 +6,7 @@ import { AnnouncementBar } from '@/ui/layout/announcement-bar';
 import { SiteHeader } from '@/ui/layout/site-header';
 import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
+import { TrackingBootstrap } from '@/components/tracking-bootstrap';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
 import { getDirection, getMessages, supportedLocales } from '@/i18n';
 import { getNonce } from '@/core/lib/nonce';
@@ -90,6 +91,16 @@ export default async function RootLayout({
               .replace(/&/g, '\\u0026'),
           }}
         />
+        {/* Google Search Console verification — token set by the merchant in
+            the dashboard (channel settings → Google site verification). Also
+            what the Merchant Center website claim checks for. Renders nothing
+            until a token is configured. */}
+        {storeInfo?.seo?.googleSiteVerification ? (
+          <meta name="google-site-verification" content={storeInfo.seo.googleSiteVerification} />
+        ) : null}
+        {/* RSS autodiscovery — feed readers and aggregators find the blog feed
+            from any page. The route itself lives at /blog/rss.xml. */}
+        <link rel="alternate" type="application/rss+xml" title="Blog" href="/blog/rss.xml" />
         {/* Brainerce cookieless traffic analytics — auto-tracks pageviews +
             SPA route changes. Cookieless (no consent banner needed); the
             merchant can toggle it per sales channel in the dashboard. */}
@@ -105,6 +116,10 @@ export default async function RootLayout({
       </head>
       <body className={font.className}>
         <StoreProvider locale={locale} initialStoreInfo={storeInfo} initialMessages={messages}>
+          {/* Mounted ahead of the page tree on purpose: React runs effects in
+              tree order, so booting the tags here guarantees fbq/ttq exist by
+              the time a page component fires its first e-commerce event. */}
+          <TrackingBootstrap />
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
@@ -125,6 +140,7 @@ import { AnnouncementBar } from '@/ui/layout/announcement-bar';
 import { SiteHeader } from '@/ui/layout/site-header';
 import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
+import { TrackingBootstrap } from '@/components/tracking-bootstrap';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
 import { getNonce } from '@/core/lib/nonce';
 import './globals.css';
@@ -197,6 +213,16 @@ export default async function RootLayout({
               .replace(/&/g, '\\u0026'),
           }}
         />
+        {/* Google Search Console verification — token set by the merchant in
+            the dashboard (channel settings → Google site verification). Also
+            what the Merchant Center website claim checks for. Renders nothing
+            until a token is configured. */}
+        {storeInfo?.seo?.googleSiteVerification ? (
+          <meta name="google-site-verification" content={storeInfo.seo.googleSiteVerification} />
+        ) : null}
+        {/* RSS autodiscovery — feed readers and aggregators find the blog feed
+            from any page. The route itself lives at /blog/rss.xml. */}
+        <link rel="alternate" type="application/rss+xml" title="Blog" href="/blog/rss.xml" />
         {/* Brainerce cookieless traffic analytics — auto-tracks pageviews +
             SPA route changes. Cookieless (no consent banner needed); the
             merchant can toggle it per sales channel in the dashboard. */}
@@ -212,6 +238,10 @@ export default async function RootLayout({
       </head>
       <body className={font.className}>
         <StoreProvider initialStoreInfo={storeInfo}>
+          {/* Mounted ahead of the page tree on purpose: React runs effects in
+              tree order, so booting the tags here guarantees fbq/ttq exist by
+              the time a page component fires its first e-commerce event. */}
+          <TrackingBootstrap />
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />

package/templates/nextjs/base/src/app/llms.txt/route.ts

@@ -2,23 +2,35 @@
  * llms.txt — GET /llms.txt
  *
  * A machine-readable site summary for AI answer engines (ChatGPT, Perplexity,
- * Claude, AI Overviews). Emerging convention: a concise markdown map of what
- * the site is and where its key content lives, so AI crawlers ground answers
- * in (and cite) the right pages.
+ * Claude, AI Overviews): a concise markdown map of what the site is and where
+ * its key content lives, so AI crawlers ground answers in (and cite) the
+ * right pages. /agents.md is the richer agent-facing companion (the newer
+ * convention) — keep the two consistent.
  */
 import { getServerClient } from '@/core/lib/brainerce';
 
 export const revalidate = 3600;
 
+interface CategoryNodeLike {
+  name: string;
+  slug?: string | null;
+  children?: CategoryNodeLike[];
+}
+
 export async function GET() {
   const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
   const client = getServerClient();
 
-  const [info, posts] = await Promise.all([
+  const [info, posts, categoriesRes] = await Promise.all([
     client.getStoreInfo().catch(() => null),
     client.blog.getPosts({ limit: 20 }).catch(() => null),
+    client.getCategories().catch(() => null),
   ]);
 
+  const topCategories: CategoryNodeLike[] = (
+    (categoriesRes?.categories as CategoryNodeLike[] | undefined) ?? []
+  ).filter((c) => c.slug);
+
   const lines: string[] = [
     `# ${info?.name ?? 'Store'}`,
     '',
@@ -26,8 +38,19 @@ export async function GET() {
     '## Key pages',
     '',
     `- [Products](${baseUrl}/products): full catalog`,
+    ...topCategories
+      .slice(0, 20)
+      .map((c) => `- [${c.name}](${baseUrl}/category/${c.slug}): category`),
     `- [Blog](${baseUrl}/blog): guides and articles`,
-    ...(info?.contactEmail ? [`- Contact: ${info.contactEmail}`] : []),
+    `- [FAQ](${baseUrl}/faq)`,
+    `- [Contact](${baseUrl}/contact)`,
+    ...(info?.contactEmail ? [`- Contact email: ${info.contactEmail}`] : []),
+    '',
+    '## Machine-readable surfaces',
+    '',
+    `- [Agent guide](${baseUrl}/agents.md)`,
+    `- [Sitemap](${baseUrl}/sitemap.xml)`,
+    `- [Blog RSS](${baseUrl}/blog/rss.xml)`,
   ];
 
   if (posts && posts.data.length > 0) {

package/templates/nextjs/base/src/app/not-found.tsx.ejs

@@ -0,0 +1,35 @@
+import Link from 'next/link';
+
+/**
+ * 404 page — rendered for unknown URLs and for `notFound()` calls from
+ * product/category/blog pages (deleted products, renamed slugs). A branded
+ * 404 with a path back to the catalog keeps the visitor (and their SEO
+ * equity) on the site instead of bouncing off the framework default.
+ */
+export default function NotFound() {
+  return (
+    <div className="mx-auto flex max-w-2xl flex-col items-center justify-center px-4 py-24 text-center">
+      <p className="text-sm font-medium text-muted-foreground">404</p>
+      <h1 className="mt-2 text-3xl font-bold tracking-tight text-foreground sm:text-4xl">
+        <%- language === 'he' ? 'העמוד לא נמצא' : 'Page not found' %>
+      </h1>
+      <p className="mt-4 text-muted-foreground">
+        <%- language === 'he' ? 'יכול להיות שהמוצר הוסר או שהכתובת השתנתה.' : 'The product may have been removed, or the address may have changed.' %>
+      </p>
+      <div className="mt-8 flex gap-4">
+        <Link
+          href="/"
+          className="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:opacity-90"
+        >
+          <%- language === 'he' ? 'לדף הבית' : 'Go home' %>
+        </Link>
+        <Link
+          href="/products"
+          className="rounded-md border border-border px-4 py-2 text-sm font-medium text-foreground hover:bg-muted"
+        >
+          <%- language === 'he' ? 'לכל המוצרים' : 'Browse products' %>
+        </Link>
+      </div>
+    </div>
+  );
+}

package/templates/nextjs/base/src/app/opengraph-image.tsx

@@ -0,0 +1,109 @@
+import { ImageResponse } from 'next/og';
+import { fetchStoreInfo } from '@/core/lib/brainerce';
+
+/**
+ * Default Open Graph card for every page that doesn't set its own og:image
+ * (home, /products, /faq, /contact, content pages without an OG image).
+ * Product / category / blog pages override this with their real images.
+ *
+ * Without this file, any page lacking an image gets NO social card at all —
+ * a bare-domain link in WhatsApp/Facebook/X renders as plain text.
+ */
+export const size = { width: 1200, height: 630 };
+export const contentType = 'image/png';
+export const alt = 'Store';
+
+/**
+ * Satori (the OG renderer) ships a Latin-only default font — a Hebrew or
+ * Arabic store name would render as tofu (□□□). Fetch a Noto Sans variant
+ * with the needed coverage at request time; fetching the CSS without a
+ * browser UA makes Google Fonts return TTF (which Satori accepts — it can't
+ * parse woff2). Cached by the framework; on any failure we render without
+ * text rather than shipping tofu.
+ */
+async function loadFont(text: string): Promise<ArrayBuffer | null> {
+  try {
+    const css = await fetch(
+      `https://fonts.googleapis.com/css2?family=Noto+Sans+Hebrew:wght@700&family=Noto+Sans:wght@700&display=swap&text=${encodeURIComponent(text)}`,
+      { cache: 'force-cache' }
+    ).then((r) => r.text());
+    const url = css.match(/src:\s*url\((.+?)\)\s*format\(['"](?:truetype|opentype)['"]\)/)?.[1];
+    if (!url) return null;
+    return await fetch(url, { cache: 'force-cache' }).then((r) => r.arrayBuffer());
+  } catch {
+    return null;
+  }
+}
+
+// Basic Latin through Latin Extended-B (U+0020–U+024F) plus whitespace,
+// punctuation, and digits — the coverage of Satori's bundled default font.
+const LATIN_ONLY = /^[ -ɏ\s\p{P}\p{N}]*$/u;
+
+export default async function OpenGraphImage() {
+  const info = await fetchStoreInfo();
+  const name = info?.name?.trim() || '';
+  const description = info?.metaDescription?.trim() || '';
+  const logo = info?.logo || null;
+
+  const text = `${name} ${description}`.trim();
+  const font = text ? await loadFont(text) : null;
+  // Default font covers Latin only — if the font fetch failed and the text
+  // needs more coverage, drop the text instead of rendering tofu.
+  const canRenderText = Boolean(text) && (font !== null || LATIN_ONLY.test(text));
+
+  return new ImageResponse(
+    <div
+      style={{
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 32,
+        background: 'linear-gradient(135deg, #111113 0%, #1c1c22 55%, #26262e 100%)',
+        color: '#fafafa',
+      }}
+    >
+      {logo ? (
+        <img src={logo} alt="" style={{ maxHeight: 220, maxWidth: 520, objectFit: 'contain' }} />
+      ) : null}
+      {canRenderText && name ? (
+        <div
+          style={{
+            display: 'flex',
+            fontSize: logo ? 56 : 84,
+            fontWeight: 700,
+            textAlign: 'center',
+            maxWidth: 1000,
+          }}
+        >
+          {name}
+        </div>
+      ) : null}
+      {canRenderText && description ? (
+        <div
+          style={{
+            display: 'flex',
+            fontSize: 32,
+            color: '#a1a1aa',
+            textAlign: 'center',
+            maxWidth: 960,
+          }}
+        >
+          {description.length > 120 ? `${description.slice(0, 119)}…` : description}
+        </div>
+      ) : null}
+    </div>,
+    {
+      ...size,
+      ...(font
+        ? {
+            fonts: [
+              { name: 'Noto Sans', data: font, weight: 700 as const, style: 'normal' as const },
+            ],
+          }
+        : {}),
+    }
+  );
+}