create-brainerce-store 1.12.3 → 1.13.0

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.12.2",
+      version: "1.13.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.12.3",
+  "version": "1.13.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/.env.local.ejs

@@ -1,5 +1,8 @@
 # Brainerce Connection
 NEXT_PUBLIC_BRAINERCE_CONNECTION_ID=<%= connectionId %>
 
-# Backend API URL (server-side only — used by BFF proxy, never exposed to browser)
+# Backend API URL (server-side only — used by BFF proxy and SSR, never exposed to browser)
 BRAINERCE_API_URL=<%= apiBaseUrl %>
+
+# Public site URL — used for sitemap, robots.txt, and SEO metadata
+NEXT_PUBLIC_SITE_URL=http://localhost:3000

package/templates/nextjs/base/src/app/order-confirmation/page.tsx

@@ -119,7 +119,9 @@ function OrderConfirmationContent() {
 
         <p className="text-muted-foreground mt-2">{t('confirmationEmail')}</p>
 
-        {result.status.orderId && <ConfirmationDownloads orderId={result.status.orderId} />}
+        {result.status.orderId && (
+          <ConfirmationDownloads orderId={result.status.orderId} checkoutId={checkoutId!} />
+        )}
 
         <div className="mt-8 flex flex-col items-center justify-center gap-3 sm:flex-row">
           <Link
@@ -180,26 +182,35 @@ function OrderConfirmationContent() {
   );
 }
 
-function ConfirmationDownloads({ orderId }: { orderId: string }) {
+function ConfirmationDownloads({ orderId, checkoutId }: { orderId: string; checkoutId: string }) {
   const t = useTranslations('orderConfirmation');
   const [downloads, setDownloads] = useState<OrderDownloadLink[] | null>(null);
 
   useEffect(() => {
     let cancelled = false;
     async function fetchDownloads() {
-      try {
-        const client = getClient();
-        const links = await client.getOrderDownloads(orderId);
-        if (!cancelled && links.length > 0) setDownloads(links);
-      } catch {
-        // Not all orders have downloads - silently ignore
+      const client = getClient();
+      // Retry a few times — the worker may still be writing downloadMeta
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const links = await client.getOrderDownloads(orderId, { checkoutId });
+          if (!cancelled && links.length > 0) {
+            setDownloads(links);
+            return;
+          }
+        } catch {
+          // Not all orders have downloads
+        }
+        if (attempt < 2 && !cancelled) {
+          await new Promise((r) => setTimeout(r, 1500));
+        }
       }
     }
     fetchDownloads();
     return () => {
       cancelled = true;
     };
-  }, [orderId]);
+  }, [orderId, checkoutId]);
 
   if (!downloads || downloads.length === 0) return null;
 

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

@@ -1,527 +1,63 @@
-'use client';
-
-import { useEffect, useState, useMemo } from 'react';
-import { useParams } from 'next/navigation';
-import Image from 'next/image';
-import Link from 'next/link';
-import type {
-  Product,
-  ProductVariant,
-  ProductImage,
-  ProductMetafield,
-  ProductRecommendationsResponse,
-  DownloadFile,
-} from 'brainerce';
-
-type ProductWithRecommendations = Product & {
-  recommendations?: ProductRecommendationsResponse;
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { getServerClient } from '@/lib/brainerce';
+import { ProductJsonLd } from '@/components/seo/product-json-ld';
+import { ProductClientSection } from './product-client-section';
+
+type Props = {
+  params: Promise<{ slug: string }>;
 };
-import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
-import { getClient } from '@/lib/brainerce';
-import { useCart } from '@/providers/store-provider';
-import { PriceDisplay } from '@/components/shared/price-display';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { VariantSelector } from '@/components/products/variant-selector';
-import { StockBadge } from '@/components/products/stock-badge';
-import { RecommendationSection } from '@/components/products/recommendation-section';
-import { useTranslations } from '@/lib/translations';
-import { cn } from '@/lib/utils';
 
-/** Render a metafield value based on its type */
-function MetafieldValue({ field }: { field: ProductMetafield }) {
-  const tc = useTranslations('common');
-  switch (field.type) {
-    case 'IMAGE': {
-      if (!field.value) return <span className="text-muted-foreground">-</span>;
-      return (
-        <img
-          src={field.value}
-          alt={field.definitionName}
-          className="h-16 w-16 rounded object-cover"
-        />
-      );
-    }
-    case 'GALLERY': {
-      let urls: string[] = [];
-      try {
-        const parsed = JSON.parse(field.value);
-        urls = Array.isArray(parsed)
-          ? parsed.filter((u: unknown) => typeof u === 'string' && u)
-          : [];
-      } catch {
-        urls = field.value ? [field.value] : [];
-      }
-      if (urls.length === 0) return <span className="text-muted-foreground">-</span>;
-      return (
-        <div className="flex flex-wrap gap-2">
-          {urls.map((url, i) => (
-            <img
-              key={i}
-              src={url}
-              alt={`${field.definitionName} ${i + 1}`}
-              className="h-16 w-16 rounded object-cover"
-            />
-          ))}
-        </div>
-      );
-    }
-    case 'URL':
-      return field.value ? (
-        <a
-          href={field.value}
-          target="_blank"
-          rel="noopener noreferrer"
-          className="text-primary break-all hover:underline"
-        >
-          {field.value}
-        </a>
-      ) : (
-        <span className="text-muted-foreground">-</span>
-      );
-    case 'COLOR':
-      return field.value ? (
-        <span className="inline-flex items-center gap-2">
-          <span
-            className="border-border inline-block h-4 w-4 rounded-full border"
-            style={{ backgroundColor: field.value }}
-          />
-          {field.value}
-        </span>
-      ) : (
-        <span className="text-muted-foreground">-</span>
-      );
-    case 'BOOLEAN':
-      return <span>{field.value === 'true' ? tc('yes') : tc('no')}</span>;
-    case 'DATE':
-    case 'DATETIME': {
-      if (!field.value) return <span className="text-muted-foreground">-</span>;
-      try {
-        const date = new Date(field.value);
-        return (
-          <span>
-            {field.type === 'DATETIME' ? date.toLocaleString() : date.toLocaleDateString()}
-          </span>
-        );
-      } catch {
-        return <span>{field.value}</span>;
-      }
-    }
-    default:
-      return <span>{field.value || '-'}</span>;
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+
+  try {
+    const client = getServerClient();
+    const product = await client.getProductBySlug(slug);
+    const imageUrl = product.images?.[0]?.url;
+    const description = product.description?.substring(0, 160) || product.name;
+
+    return {
+      title: product.name,
+      description,
+      openGraph: {
+        title: product.name,
+        description,
+        images: imageUrl ? [{ url: imageUrl, alt: product.name }] : [],
+        type: 'website',
+      },
+      twitter: {
+        card: 'summary_large_image',
+        title: product.name,
+        description,
+        images: imageUrl ? [imageUrl] : [],
+      },
+    };
+  } catch {
+    return {
+      title: 'Product not found',
+    };
   }
 }
 
-export default function ProductDetailPage() {
-  const params = useParams();
-  const slug = params.slug as string;
-  const { refreshCart } = useCart();
-  const t = useTranslations('productDetail');
-  const tc = useTranslations('common');
-  const [product, setProduct] = useState<ProductWithRecommendations | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(null);
-  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
-  const [quantity, setQuantity] = useState(1);
-  const [addingToCart, setAddingToCart] = useState(false);
-  const [addedMessage, setAddedMessage] = useState(false);
-
-  const recommendations = product?.recommendations ?? null;
-
-  // Load product
-  useEffect(() => {
-    async function load() {
-      try {
-        setLoading(true);
-        setError(null);
-        const client = getClient();
-        const p = await client.getProductBySlug(slug);
-        setProduct(p as ProductWithRecommendations);
-
-        // Auto-select first variant
-        if (p.variants && p.variants.length > 0) {
-          setSelectedVariant(p.variants[0]);
-        }
-      } catch {
-        setError(t('notFound'));
-      } finally {
-        setLoading(false);
-      }
-    }
-    load();
-  }, [slug]);
-
-  // Images list - switch main image when variant changes
-  const images: ProductImage[] = useMemo(() => {
-    return product?.images || [];
-  }, [product]);
-
-  // When variant changes, update selected image to variant image if available
-  useEffect(() => {
-    if (!selectedVariant?.image || !product) return;
-
-    const variantImgUrl =
-      typeof selectedVariant.image === 'string' ? selectedVariant.image : selectedVariant.image.url;
+export default async function ProductDetailPage({ params }: Props) {
+  const { slug } = await params;
 
-    // Find if variant image exists in product images
-    const idx = images.findIndex((img) => img.url === variantImgUrl);
-    if (idx >= 0) {
-      setSelectedImageIndex(idx);
-    } else {
-      // Variant image not in product images - select index 0 as fallback
-      // (The variant image will be shown as the main image via override)
-      setSelectedImageIndex(-1);
-    }
-  }, [selectedVariant, images, product]);
-
-  // Determine which image to show
-  const mainImageUrl = useMemo(() => {
-    if (selectedImageIndex === -1 && selectedVariant?.image) {
-      const img = selectedVariant.image;
-      return typeof img === 'string' ? img : img.url;
-    }
-    return images[selectedImageIndex]?.url || null;
-  }, [selectedImageIndex, selectedVariant, images]);
-
-  // Price info - use variant price if selected, else product price
-  const priceInfo = useMemo(() => {
-    if (selectedVariant?.price) {
-      return {
-        price: parseFloat(selectedVariant.salePrice || selectedVariant.price),
-        originalPrice: parseFloat(selectedVariant.price),
-        isOnSale:
-          selectedVariant.salePrice != null &&
-          parseFloat(selectedVariant.salePrice) < parseFloat(selectedVariant.price),
-        discountPercent:
-          selectedVariant.salePrice != null &&
-          parseFloat(selectedVariant.salePrice) < parseFloat(selectedVariant.price)
-            ? Math.round(
-                ((parseFloat(selectedVariant.price) - parseFloat(selectedVariant.salePrice)) /
-                  parseFloat(selectedVariant.price)) *
-                  100
-              )
-            : 0,
-      };
-    }
-    return getProductPriceInfo(product);
-  }, [product, selectedVariant]);
-
-  // Inventory: use variant inventory if selected, else product inventory
-  const inventory = selectedVariant?.inventory ?? product?.inventory ?? null;
-  const canPurchase = inventory?.canPurchase !== false;
-
-  // Description
-  const description = useMemo(() => {
-    return product ? getDescriptionContent(product) : null;
-  }, [product]);
-
-  async function handleAddToCart() {
-    if (!product || addingToCart) return;
-
-    try {
-      setAddingToCart(true);
-      const client = getClient();
-      await client.smartAddToCart({
-        productId: product.id,
-        variantId: selectedVariant?.id,
-        quantity,
-        name: product.name,
-        price: String(priceInfo.price),
-        image: mainImageUrl || undefined,
-      });
-      await refreshCart();
-      setAddedMessage(true);
-      setTimeout(() => setAddedMessage(false), 2000);
-    } catch (err) {
-      console.error('Failed to add to cart:', err);
-    } finally {
-      setAddingToCart(false);
-    }
+  let product;
+  try {
+    const client = getServerClient();
+    product = await client.getProductBySlug(slug);
+  } catch {
+    notFound();
   }
 
-  if (loading) {
-    return (
-      <div className="flex min-h-[60vh] items-center justify-center">
-        <LoadingSpinner size="lg" />
-      </div>
-    );
-  }
-
-  if (error || !product) {
-    return (
-      <div className="mx-auto max-w-7xl px-4 py-16 text-center sm:px-6 lg:px-8">
-        <h1 className="text-foreground text-2xl font-bold">{error || t('notFound')}</h1>
-        <Link href="/products" className="text-primary mt-4 inline-block hover:underline">
-          {t('backToProducts')}
-        </Link>
-      </div>
-    );
-  }
+  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || '';
+  const productUrl = `${baseUrl}/products/${slug}`;
 
   return (
-    <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
-      <div className="grid grid-cols-1 gap-8 lg:grid-cols-2 lg:gap-12">
-        {/* Image Gallery */}
-        <div className="space-y-4">
-          {/* Main Image */}
-          <div className="bg-muted relative aspect-square overflow-hidden rounded-lg">
-            {mainImageUrl ? (
-              <Image
-                src={mainImageUrl}
-                alt={product.name}
-                fill
-                sizes="(max-width: 1024px) 100vw, 50vw"
-                className="object-contain"
-                priority
-              />
-            ) : (
-              <div className="text-muted-foreground absolute inset-0 flex items-center justify-center">
-                <svg className="h-24 w-24" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={1}
-                    d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
-                  />
-                </svg>
-              </div>
-            )}
-          </div>
-
-          {/* Thumbnails */}
-          {images.length > 1 && (
-            <div className="flex gap-2 overflow-x-auto pb-2">
-              {images.map((img, idx) => (
-                <button
-                  key={idx}
-                  type="button"
-                  onClick={() => setSelectedImageIndex(idx)}
-                  className={cn(
-                    'relative h-16 w-16 flex-shrink-0 overflow-hidden rounded border-2 transition-colors',
-                    selectedImageIndex === idx
-                      ? 'border-primary'
-                      : 'border-border hover:border-muted-foreground'
-                  )}
-                >
-                  <Image
-                    src={img.url}
-                    alt={img.alt || `${product.name} ${idx + 1}`}
-                    fill
-                    sizes="64px"
-                    className="object-cover"
-                  />
-                </button>
-              ))}
-            </div>
-          )}
-        </div>
-
-        {/* Product Info */}
-        <div className="space-y-6">
-          {/* Categories */}
-          {product.categories && product.categories.length > 0 && (
-            <div className="flex flex-wrap gap-2">
-              {product.categories.map((cat) => (
-                <span
-                  key={cat.id}
-                  className="text-muted-foreground bg-muted rounded px-2 py-1 text-xs"
-                >
-                  {cat.name}
-                </span>
-              ))}
-            </div>
-          )}
-
-          {/* Title */}
-          <h1 className="text-foreground text-2xl font-bold sm:text-3xl">{product.name}</h1>
-
-          {/* Price */}
-          <PriceDisplay
-            price={priceInfo.originalPrice}
-            salePrice={priceInfo.isOnSale ? priceInfo.price : undefined}
-            size="lg"
-          />
-
-          {/* Stock / Digital badge */}
-          {product.isDownloadable ? (
-            <span className="inline-flex items-center gap-1.5 rounded-full bg-green-100 px-3 py-1 text-xs font-medium text-green-800 dark:bg-green-950/30 dark:text-green-400">
-              <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={2}
-                  d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4"
-                />
-              </svg>
-              {t('instantDownload')}
-            </span>
-          ) : (
-            <StockBadge inventory={inventory} lowStockThreshold={5} />
-          )}
-
-          {/* Downloadable files info */}
-          {product.isDownloadable && product.downloads && product.downloads.length > 0 && (
-            <div className="bg-muted/50 rounded-lg border p-4">
-              <p className="text-foreground mb-2 text-sm font-medium">
-                {t('filesIncluded', { count: product.downloads.length })}
-              </p>
-              <ul className="space-y-1.5">
-                {product.downloads.map((file: DownloadFile) => (
-                  <li
-                    key={file.id}
-                    className="text-muted-foreground flex items-center gap-2 text-sm"
-                  >
-                    <svg
-                      className="h-4 w-4 flex-shrink-0"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={1.5}
-                        d="M7 21h10a2 2 0 002-2V9.414a1 1 0 00-.293-.707l-5.414-5.414A1 1 0 0012.586 3H7a2 2 0 00-2 2v14a2 2 0 002 2z"
-                      />
-                    </svg>
-                    <span className="truncate">{file.name}</span>
-                    {file.size && (
-                      <span className="flex-shrink-0 text-xs">
-                        (
-                        {file.size < 1024 * 1024
-                          ? `${(file.size / 1024).toFixed(0)} KB`
-                          : `${(file.size / (1024 * 1024)).toFixed(1)} MB`}
-                        )
-                      </span>
-                    )}
-                  </li>
-                ))}
-              </ul>
-            </div>
-          )}
-
-          {/* Variant Selector */}
-          {product.type === 'VARIABLE' && product.variants && product.variants.length > 0 && (
-            <VariantSelector
-              product={product}
-              selectedVariant={selectedVariant}
-              onVariantChange={setSelectedVariant}
-            />
-          )}
-
-          {/* Quantity + Add to Cart */}
-          <div className="flex items-center gap-4">
-            <div className="border-border flex items-center rounded border">
-              <button
-                type="button"
-                onClick={() => setQuantity((q) => Math.max(1, q - 1))}
-                className="text-foreground hover:bg-muted px-3 py-2 transition-colors"
-                aria-label={t('decreaseQuantity')}
-              >
-                -
-              </button>
-              <span className="text-foreground min-w-[3rem] px-4 py-2 text-center text-sm font-medium">
-                {quantity}
-              </span>
-              <button
-                type="button"
-                onClick={() => setQuantity((q) => q + 1)}
-                className="text-foreground hover:bg-muted px-3 py-2 transition-colors"
-                aria-label={t('increaseQuantity')}
-              >
-                +
-              </button>
-            </div>
-
-            <button
-              type="button"
-              onClick={handleAddToCart}
-              disabled={!canPurchase || addingToCart}
-              className={cn(
-                'flex-1 rounded px-6 py-3 text-sm font-medium transition-all',
-                canPurchase
-                  ? 'bg-primary text-primary-foreground hover:opacity-90'
-                  : 'bg-muted text-muted-foreground cursor-not-allowed'
-              )}
-            >
-              {addingToCart ? (
-                <span className="inline-flex items-center gap-2">
-                  <LoadingSpinner
-                    size="sm"
-                    className="border-primary-foreground/30 border-t-primary-foreground"
-                  />
-                  {t('addingToCart')}
-                </span>
-              ) : addedMessage ? (
-                t('addedToCart')
-              ) : !canPurchase ? (
-                t('outOfStock')
-              ) : (
-                t('addToCart')
-              )}
-            </button>
-          </div>
-
-          {/* Download after purchase note */}
-          {product.isDownloadable && (
-            <p className="text-muted-foreground text-sm">{t('downloadAfterPurchase')}</p>
-          )}
-
-          {/* Description */}
-          {description && (
-            <div className="border-border border-t pt-4">
-              <h2 className="text-foreground mb-3 text-lg font-semibold">{t('description')}</h2>
-              {'html' in description ? (
-                <div
-                  className="prose prose-sm text-muted-foreground max-w-none"
-                  dangerouslySetInnerHTML={{ __html: description.html }}
-                />
-              ) : (
-                <p className="text-muted-foreground whitespace-pre-wrap">{description.text}</p>
-              )}
-            </div>
-          )}
-
-          {/* Metafields / Specifications */}
-          {product.metafields && product.metafields.length > 0 && (
-            <div className="border-border border-t pt-4">
-              <h2 className="text-foreground mb-3 text-lg font-semibold">{t('specifications')}</h2>
-              <table className="w-full text-sm">
-                <tbody>
-                  {product.metafields.map((field) => (
-                    <tr key={field.id} className="border-border border-b last:border-0">
-                      <td className="text-foreground whitespace-nowrap py-2 pe-4 font-medium">
-                        {field.definitionName}
-                      </td>
-                      <td className="text-muted-foreground py-2">
-                        <MetafieldValue field={field} />
-                      </td>
-                    </tr>
-                  ))}
-                </tbody>
-              </table>
-            </div>
-          )}
-        </div>
-      </div>
-
-      {/* Upsells — premium alternatives (product page) */}
-      {recommendations?.upsells && recommendations.upsells.length > 0 && (
-        <RecommendationSection
-          title={t('upgradeYourChoice')}
-          items={recommendations.upsells}
-          className="mt-12"
-        />
-      )}
-
-      {/* Related products — similar items (bottom of product page) */}
-      {recommendations?.related && recommendations.related.length > 0 && (
-        <RecommendationSection
-          title={t('similarProducts')}
-          items={recommendations.related}
-          className="mt-12"
-        />
-      )}
-    </div>
+    <>
+      <ProductJsonLd product={product} url={productUrl} />
+      <ProductClientSection product={product} />
+    </>
   );
 }

package/templates/nextjs/base/src/app/products/[slug]/product-client-section.tsx

@@ -0,0 +1,485 @@
+'use client';
+
+import { useEffect, useState, useMemo } from 'react';
+import Image from 'next/image';
+import type {
+  Product,
+  ProductVariant,
+  ProductImage,
+  ProductMetafield,
+  ProductRecommendationsResponse,
+  DownloadFile,
+} from 'brainerce';
+
+type ProductWithRecommendations = Product & {
+  recommendations?: ProductRecommendationsResponse;
+};
+import { getProductPriceInfo, getDescriptionContent } from 'brainerce';
+import { useCart } from '@/providers/store-provider';
+import { PriceDisplay } from '@/components/shared/price-display';
+import { LoadingSpinner } from '@/components/shared/loading-spinner';
+import { VariantSelector } from '@/components/products/variant-selector';
+import { StockBadge } from '@/components/products/stock-badge';
+import { RecommendationSection } from '@/components/products/recommendation-section';
+import { useTranslations } from '@/lib/translations';
+import { cn } from '@/lib/utils';
+
+/** Render a metafield value based on its type */
+function MetafieldValue({ field }: { field: ProductMetafield }) {
+  const tc = useTranslations('common');
+  switch (field.type) {
+    case 'IMAGE': {
+      if (!field.value) return <span className="text-muted-foreground">-</span>;
+      return (
+        <img
+          src={field.value}
+          alt={field.definitionName}
+          className="h-16 w-16 rounded object-cover"
+        />
+      );
+    }
+    case 'GALLERY': {
+      let urls: string[] = [];
+      try {
+        const parsed = JSON.parse(field.value);
+        urls = Array.isArray(parsed)
+          ? parsed.filter((u: unknown) => typeof u === 'string' && u)
+          : [];
+      } catch {
+        urls = field.value ? [field.value] : [];
+      }
+      if (urls.length === 0) return <span className="text-muted-foreground">-</span>;
+      return (
+        <div className="flex flex-wrap gap-2">
+          {urls.map((url, i) => (
+            <img
+              key={i}
+              src={url}
+              alt={`${field.definitionName} ${i + 1}`}
+              className="h-16 w-16 rounded object-cover"
+            />
+          ))}
+        </div>
+      );
+    }
+    case 'URL':
+      return field.value ? (
+        <a
+          href={field.value}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-primary break-all hover:underline"
+        >
+          {field.value}
+        </a>
+      ) : (
+        <span className="text-muted-foreground">-</span>
+      );
+    case 'COLOR':
+      return field.value ? (
+        <span className="inline-flex items-center gap-2">
+          <span
+            className="border-border inline-block h-4 w-4 rounded-full border"
+            style={{ backgroundColor: field.value }}
+          />
+          {field.value}
+        </span>
+      ) : (
+        <span className="text-muted-foreground">-</span>
+      );
+    case 'BOOLEAN':
+      return <span>{field.value === 'true' ? tc('yes') : tc('no')}</span>;
+    case 'DATE':
+    case 'DATETIME': {
+      if (!field.value) return <span className="text-muted-foreground">-</span>;
+      try {
+        const date = new Date(field.value);
+        return (
+          <span>
+            {field.type === 'DATETIME' ? date.toLocaleString() : date.toLocaleDateString()}
+          </span>
+        );
+      } catch {
+        return <span>{field.value}</span>;
+      }
+    }
+    default:
+      return <span>{field.value || '-'}</span>;
+  }
+}
+
+interface ProductClientSectionProps {
+  product: Product;
+}
+
+export function ProductClientSection({ product: initialProduct }: ProductClientSectionProps) {
+  const { refreshCart } = useCart();
+  const t = useTranslations('productDetail');
+  const tc = useTranslations('common');
+
+  const product = initialProduct as ProductWithRecommendations;
+  const recommendations = product?.recommendations ?? null;
+
+  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(
+    product.variants && product.variants.length > 0 ? product.variants[0] : null
+  );
+  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
+  const [quantity, setQuantity] = useState(1);
+  const [addingToCart, setAddingToCart] = useState(false);
+  const [addedMessage, setAddedMessage] = useState(false);
+
+  // Images list - switch main image when variant changes
+  const images: ProductImage[] = useMemo(() => {
+    return product?.images || [];
+  }, [product]);
+
+  // When variant changes, update selected image to variant image if available
+  useEffect(() => {
+    if (!selectedVariant?.image || !product) return;
+
+    const variantImgUrl =
+      typeof selectedVariant.image === 'string' ? selectedVariant.image : selectedVariant.image.url;
+
+    // Find if variant image exists in product images
+    const idx = images.findIndex((img) => img.url === variantImgUrl);
+    if (idx >= 0) {
+      setSelectedImageIndex(idx);
+    } else {
+      // Variant image not in product images - select index 0 as fallback
+      setSelectedImageIndex(-1);
+    }
+  }, [selectedVariant, images, product]);
+
+  // Determine which image to show
+  const mainImageUrl = useMemo(() => {
+    if (selectedImageIndex === -1 && selectedVariant?.image) {
+      const img = selectedVariant.image;
+      return typeof img === 'string' ? img : img.url;
+    }
+    return images[selectedImageIndex]?.url || null;
+  }, [selectedImageIndex, selectedVariant, images]);
+
+  // Price info - use variant price if selected, else product price
+  const priceInfo = useMemo(() => {
+    if (selectedVariant?.price) {
+      return {
+        price: parseFloat(selectedVariant.salePrice || selectedVariant.price),
+        originalPrice: parseFloat(selectedVariant.price),
+        isOnSale:
+          selectedVariant.salePrice != null &&
+          parseFloat(selectedVariant.salePrice) < parseFloat(selectedVariant.price),
+        discountPercent:
+          selectedVariant.salePrice != null &&
+          parseFloat(selectedVariant.salePrice) < parseFloat(selectedVariant.price)
+            ? Math.round(
+                ((parseFloat(selectedVariant.price) - parseFloat(selectedVariant.salePrice)) /
+                  parseFloat(selectedVariant.price)) *
+                  100
+              )
+            : 0,
+      };
+    }
+    return getProductPriceInfo(product);
+  }, [product, selectedVariant]);
+
+  // Inventory: use variant inventory if selected, else product inventory
+  const inventory = selectedVariant?.inventory ?? product?.inventory ?? null;
+  const canPurchase = inventory?.canPurchase !== false;
+
+  // Description
+  const description = useMemo(() => {
+    return product ? getDescriptionContent(product) : null;
+  }, [product]);
+
+  async function handleAddToCart() {
+    if (!product || addingToCart) return;
+
+    try {
+      setAddingToCart(true);
+      const { getClient } = await import('@/lib/brainerce');
+      const client = getClient();
+      await client.smartAddToCart({
+        productId: product.id,
+        variantId: selectedVariant?.id,
+        quantity,
+        name: product.name,
+        price: String(priceInfo.price),
+        image: mainImageUrl || undefined,
+      });
+      await refreshCart();
+      setAddedMessage(true);
+      setTimeout(() => setAddedMessage(false), 2000);
+    } catch (err) {
+      console.error('Failed to add to cart:', err);
+    } finally {
+      setAddingToCart(false);
+    }
+  }
+
+  return (
+    <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
+      <div className="grid grid-cols-1 gap-8 lg:grid-cols-2 lg:gap-12">
+        {/* Image Gallery */}
+        <div className="space-y-4">
+          {/* Main Image */}
+          <div className="bg-muted relative aspect-square overflow-hidden rounded-lg">
+            {mainImageUrl ? (
+              <Image
+                src={mainImageUrl}
+                alt={product.name}
+                fill
+                sizes="(max-width: 1024px) 100vw, 50vw"
+                className="object-contain"
+                priority
+              />
+            ) : (
+              <div className="text-muted-foreground absolute inset-0 flex items-center justify-center">
+                <svg className="h-24 w-24" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={1}
+                    d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+                  />
+                </svg>
+              </div>
+            )}
+          </div>
+
+          {/* Thumbnails */}
+          {images.length > 1 && (
+            <div className="flex gap-2 overflow-x-auto pb-2">
+              {images.map((img, idx) => (
+                <button
+                  key={idx}
+                  type="button"
+                  onClick={() => setSelectedImageIndex(idx)}
+                  className={cn(
+                    'relative h-16 w-16 flex-shrink-0 overflow-hidden rounded border-2 transition-colors',
+                    selectedImageIndex === idx
+                      ? 'border-primary'
+                      : 'border-border hover:border-muted-foreground'
+                  )}
+                >
+                  <Image
+                    src={img.url}
+                    alt={img.alt || `${product.name} ${idx + 1}`}
+                    fill
+                    sizes="64px"
+                    className="object-cover"
+                  />
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+
+        {/* Product Info */}
+        <div className="space-y-6">
+          {/* Categories */}
+          {product.categories && product.categories.length > 0 && (
+            <div className="flex flex-wrap gap-2">
+              {product.categories.map((cat) => (
+                <span
+                  key={cat.id}
+                  className="text-muted-foreground bg-muted rounded px-2 py-1 text-xs"
+                >
+                  {cat.name}
+                </span>
+              ))}
+            </div>
+          )}
+
+          {/* Title */}
+          <h1 className="text-foreground text-2xl font-bold sm:text-3xl">{product.name}</h1>
+
+          {/* Price */}
+          <PriceDisplay
+            price={priceInfo.originalPrice}
+            salePrice={priceInfo.isOnSale ? priceInfo.price : undefined}
+            size="lg"
+          />
+
+          {/* Stock / Digital badge */}
+          {product.isDownloadable ? (
+            <span className="inline-flex items-center gap-1.5 rounded-full bg-green-100 px-3 py-1 text-xs font-medium text-green-800 dark:bg-green-950/30 dark:text-green-400">
+              <svg className="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4"
+                />
+              </svg>
+              {t('instantDownload')}
+            </span>
+          ) : (
+            <StockBadge inventory={inventory} lowStockThreshold={5} />
+          )}
+
+          {/* Downloadable files info */}
+          {product.isDownloadable && product.downloads && product.downloads.length > 0 && (
+            <div className="bg-muted/50 rounded-lg border p-4">
+              <p className="text-foreground mb-2 text-sm font-medium">
+                {t('filesIncluded', { count: product.downloads.length })}
+              </p>
+              <ul className="space-y-1.5">
+                {product.downloads.map((file: DownloadFile) => (
+                  <li
+                    key={file.id}
+                    className="text-muted-foreground flex items-center gap-2 text-sm"
+                  >
+                    <svg
+                      className="h-4 w-4 flex-shrink-0"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={1.5}
+                        d="M7 21h10a2 2 0 002-2V9.414a1 1 0 00-.293-.707l-5.414-5.414A1 1 0 0012.586 3H7a2 2 0 00-2 2v14a2 2 0 002 2z"
+                      />
+                    </svg>
+                    <span className="truncate">{file.name}</span>
+                    {file.size && (
+                      <span className="flex-shrink-0 text-xs">
+                        (
+                        {file.size < 1024 * 1024
+                          ? `${(file.size / 1024).toFixed(0)} KB`
+                          : `${(file.size / (1024 * 1024)).toFixed(1)} MB`}
+                        )
+                      </span>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          {/* Variant Selector */}
+          {product.type === 'VARIABLE' && product.variants && product.variants.length > 0 && (
+            <VariantSelector
+              product={product}
+              selectedVariant={selectedVariant}
+              onVariantChange={setSelectedVariant}
+            />
+          )}
+
+          {/* Quantity + Add to Cart */}
+          <div className="flex items-center gap-4">
+            <div className="border-border flex items-center rounded border">
+              <button
+                type="button"
+                onClick={() => setQuantity((q) => Math.max(1, q - 1))}
+                className="text-foreground hover:bg-muted px-3 py-2 transition-colors"
+                aria-label={t('decreaseQuantity')}
+              >
+                -
+              </button>
+              <span className="text-foreground min-w-[3rem] px-4 py-2 text-center text-sm font-medium">
+                {quantity}
+              </span>
+              <button
+                type="button"
+                onClick={() => setQuantity((q) => q + 1)}
+                className="text-foreground hover:bg-muted px-3 py-2 transition-colors"
+                aria-label={t('increaseQuantity')}
+              >
+                +
+              </button>
+            </div>
+
+            <button
+              type="button"
+              onClick={handleAddToCart}
+              disabled={!canPurchase || addingToCart}
+              className={cn(
+                'flex-1 rounded px-6 py-3 text-sm font-medium transition-all',
+                canPurchase
+                  ? 'bg-primary text-primary-foreground hover:opacity-90'
+                  : 'bg-muted text-muted-foreground cursor-not-allowed'
+              )}
+            >
+              {addingToCart ? (
+                <span className="inline-flex items-center gap-2">
+                  <LoadingSpinner
+                    size="sm"
+                    className="border-primary-foreground/30 border-t-primary-foreground"
+                  />
+                  {t('addingToCart')}
+                </span>
+              ) : addedMessage ? (
+                t('addedToCart')
+              ) : !canPurchase ? (
+                t('outOfStock')
+              ) : (
+                t('addToCart')
+              )}
+            </button>
+          </div>
+
+          {/* Download after purchase note */}
+          {product.isDownloadable && (
+            <p className="text-muted-foreground text-sm">{t('downloadAfterPurchase')}</p>
+          )}
+
+          {/* Description */}
+          {description && (
+            <div className="border-border border-t pt-4">
+              <h2 className="text-foreground mb-3 text-lg font-semibold">{t('description')}</h2>
+              {'html' in description ? (
+                <div
+                  className="prose prose-sm text-muted-foreground max-w-none"
+                  dangerouslySetInnerHTML={{ __html: description.html }}
+                />
+              ) : (
+                <p className="text-muted-foreground whitespace-pre-wrap">{description.text}</p>
+              )}
+            </div>
+          )}
+
+          {/* Metafields / Specifications */}
+          {product.metafields && product.metafields.length > 0 && (
+            <div className="border-border border-t pt-4">
+              <h2 className="text-foreground mb-3 text-lg font-semibold">{t('specifications')}</h2>
+              <table className="w-full text-sm">
+                <tbody>
+                  {product.metafields.map((field) => (
+                    <tr key={field.id} className="border-border border-b last:border-0">
+                      <td className="text-foreground whitespace-nowrap py-2 pe-4 font-medium">
+                        {field.definitionName}
+                      </td>
+                      <td className="text-muted-foreground py-2">
+                        <MetafieldValue field={field} />
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Upsells */}
+      {recommendations?.upsells && recommendations.upsells.length > 0 && (
+        <RecommendationSection
+          title={t('upgradeYourChoice')}
+          items={recommendations.upsells}
+          className="mt-12"
+        />
+      )}
+
+      {/* Related products */}
+      {recommendations?.related && recommendations.related.length > 0 && (
+        <RecommendationSection
+          title={t('similarProducts')}
+          items={recommendations.related}
+          className="mt-12"
+        />
+      )}
+    </div>
+  );
+}

package/templates/nextjs/base/src/app/robots.ts

@@ -0,0 +1,14 @@
+import type { MetadataRoute } from 'next';
+
+export default function robots(): MetadataRoute.Robots {
+  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
+
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: ['/api/', '/auth/', '/checkout/', '/account/'],
+    },
+    sitemap: `${baseUrl}/sitemap.xml`,
+  };
+}

package/templates/nextjs/base/src/app/sitemap.ts

@@ -0,0 +1,25 @@
+import type { MetadataRoute } from 'next';
+import { getServerClient } from '@/lib/brainerce';
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
+
+  const staticPages: MetadataRoute.Sitemap = [
+    { url: baseUrl, lastModified: new Date(), priority: 1 },
+    { url: `${baseUrl}/products`, lastModified: new Date(), priority: 0.9 },
+  ];
+
+  try {
+    const client = getServerClient();
+    const { data: products } = await client.getProducts({ limit: 1000 });
+    const productPages: MetadataRoute.Sitemap = products.map((product) => ({
+      url: `${baseUrl}/products/${product.slug}`,
+      lastModified: product.updatedAt ? new Date(product.updatedAt) : new Date(),
+      priority: 0.8,
+    }));
+
+    return [...staticPages, ...productPages];
+  } catch {
+    return staticPages;
+  }
+}

package/templates/nextjs/base/src/components/seo/product-json-ld.tsx

@@ -0,0 +1,39 @@
+import type { Product } from 'brainerce';
+import { getProductPriceInfo } from 'brainerce';
+
+interface ProductJsonLdProps {
+  product: Product;
+  url: string;
+}
+
+export function ProductJsonLd({ product, url }: ProductJsonLdProps) {
+  const priceInfo = getProductPriceInfo(product);
+  const imageUrl = product.images?.[0]?.url;
+
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: product.name,
+    description: product.description || product.name,
+    image: imageUrl,
+    url,
+    sku: product.sku || product.id,
+    offers: {
+      '@type': 'Offer',
+      price: priceInfo.price,
+      priceCurrency: 'ILS',
+      availability:
+        product.inventory?.canPurchase !== false
+          ? 'https://schema.org/InStock'
+          : 'https://schema.org/OutOfStock',
+      url,
+    },
+  };
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+    />
+  );
+}

package/templates/nextjs/base/src/lib/brainerce.ts.ejs

@@ -37,3 +37,13 @@ export function setStoredCartId(cartId: string | null): void {
 export function initClient(): BrainerceClient {
   return getClient();
 }
+
+// Server-side client — calls backend directly (no proxy needed for public data)
+// Used by Server Components for SSR data fetching (generateMetadata, page rendering)
+export function getServerClient(): BrainerceClient {
+  const apiUrl = process.env.BRAINERCE_API_URL || 'https://api.brainerce.com';
+  return new BrainerceClient({
+    connectionId: CONNECTION_ID,
+    baseUrl: apiUrl,
+  });
+}