create-brainerce-store 1.41.0 → 1.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"
@@ -33,7 +33,7 @@
     "typescript": "^5.4.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
   },
   "keywords": [
     "brainerce",

package/templates/nextjs/base/TRANSLATIONS.md

@@ -0,0 +1,200 @@
+# Multi-language storefronts
+
+Your scaffolded Brainerce store is already wired for multi-language out of the box. This doc explains the moving parts so you can customize them — you do **not** need to write per-locale fetch code; the SDK + middleware do it for you.
+
+## Status check
+
+```typescript
+const store = await client.getStoreInfo();
+store.i18n?.enabled; // → true / false
+store.i18n?.defaultLocale; // → e.g. "en"
+store.i18n?.supportedLocales; // → e.g. ["en", "he"]
+```
+
+If `i18n.enabled` is `false` or only one locale is supported, the rest of this doc is a no-op — the app behaves as a single-language store.
+
+## URL strategy: "as-needed" locale prefix
+
+This template uses the as-needed pattern (the most common approach for SEO):
+
+| URL            | Locale  | Notes                                             |
+| -------------- | ------- | ------------------------------------------------- |
+| `/`            | default | Clean URL — no `/en` prefix on the default locale |
+| `/products`    | default | Same                                              |
+| `/he`          | Hebrew  | Secondary locales get a path prefix               |
+| `/he/products` | Hebrew  | Same                                              |
+
+The middleware (`src/middleware.ts`) handles two transitions:
+
+1. `/{defaultLocale}/X` → 308 redirect to `/X` (canonicalize away the redundant prefix)
+2. `/X` → internal rewrite to `/{defaultLocale}/X` so the Next.js `[locale]` route segment still resolves
+
+Every response carries an `x-locale` header so Server Components can read the resolved locale via `headers()`.
+
+## How translated content shows up on the page
+
+You write **one** `fetch` and it works for every language.
+
+```tsx
+// src/app/[locale]/products/[slug]/page.tsx
+import { getServerClient } from '@/lib/server-client';
+import { headers } from 'next/headers';
+
+export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const locale = (await headers()).get('x-locale') ?? undefined;
+  const client = getServerClient();
+  client.setLocale(locale);
+
+  const product = await client.getProductBySlug(slug);
+  // product.name, product.description, product.categories[].name, modifier groups,
+  // metafield labels — all already translated by the server.
+
+  return <ProductDetail product={product} />;
+}
+```
+
+The `StoreProvider` (`src/providers/store-provider.tsx`) calls `client.setLocale(locale)` on the client side, so React Server Components and Client Components both get translated content.
+
+## What's translatable (full list)
+
+| Entity                  | Fields                                                      |
+| ----------------------- | ----------------------------------------------------------- |
+| **Product**             | `name`, `description`, `slug`, `seoTitle`, `seoDescription` |
+| **ProductVariant**      | `name`                                                      |
+| **Category**            | `name`                                                      |
+| **Brand**               | `name`                                                      |
+| **Tag**                 | `name`                                                      |
+| **Attribute**           | `name` (e.g. "Color")                                       |
+| **AttributeOption**     | `name` (e.g. "Red")                                         |
+| **ModifierGroup**       | `name`, `description` (e.g. "Toppings" → "תוספות")          |
+| **Modifier**            | `name`, `description` (e.g. "Olives" → "זיתים")             |
+| **ProductMetafield**    | `value` (free-text custom field values)                     |
+| **MetafieldDefinition** | `name`, `description` (custom-field labels)                 |
+| **BundleOffer**         | `name`, `description` (bundle marketing label)              |
+| **OrderBumpConfig**     | `title`, `description` (bump headline at checkout)          |
+| **DiscountRule**        | `name`, `description` (rule label, used in banners)         |
+| **ContactForm**         | `name`, `description`, `submitButton`, `successMessage`     |
+| **ContactFormField**    | `label`, `placeholder`, `helpText`                          |
+
+You never overlay translations yourself — the SDK does it on every request.
+
+## RTL (Hebrew, Arabic, Persian, Urdu, Yiddish)
+
+`src/i18n.ts` exports `getDirection(locale)` that delegates to the SDK's `getDirectionForLocale()`. The layout uses it on `<html dir={…}>`:
+
+```tsx
+// src/app/[locale]/layout.tsx
+import { getDirection } from '@/i18n';
+
+export default async function LocaleLayout({ children, params }: Props) {
+  const { locale } = await params;
+  const dir = getDirection(locale);
+  return (
+    <html lang={locale} dir={dir}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+This automatically reverses flexbox row order — **do not add `flex-row-reverse`** on top, that's a double-swap. **Do** swap directional icons (chevrons, arrows) using `useDirection()` from `@radix-ui/react-direction`.
+
+Use logical Tailwind classes (`ms-*`/`me-*` for margin, `ps-*`/`pe-*` for padding, `start-*`/`end-*` for positioning) instead of physical ones (`ml-*`, `mr-*`, `left-*`, `right-*`) so the layout mirrors automatically.
+
+## Language switcher
+
+```tsx
+'use client';
+import { useStore } from '@/providers/store-provider';
+import Link from 'next/link';
+import { useParams, usePathname } from 'next/navigation';
+
+export function LanguageSwitcher() {
+  const { storeInfo } = useStore();
+  const pathname = usePathname();
+  const { locale: current } = useParams<{ locale?: string }>();
+
+  if (!storeInfo?.i18n?.enabled) return null;
+  const locales = storeInfo.i18n.supportedLocales;
+  const defaultLocale = storeInfo.i18n.defaultLocale;
+
+  return (
+    <nav className="flex gap-2">
+      {locales.map((loc) => {
+        const isCurrent = (current ?? defaultLocale) === loc;
+        const href = loc === defaultLocale ? pathname : `/${loc}${pathname}`;
+        return (
+          <Link key={loc} href={href} className={isCurrent ? 'font-bold' : ''}>
+            {loc.toUpperCase()}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}
+```
+
+The merchant configures supported locales in `Dashboard → Settings → Languages`. Your switcher reads them from `storeInfo.i18n.supportedLocales` — never hardcode a list.
+
+## SEO: per-locale slugs and hreflang
+
+When the merchant translates a product's `slug`, every locale gets its own URL (e.g. `/cheese-pizza` and `/he/פיצה-גבינה`). Pull all alternates in one call for the `<head>`:
+
+```tsx
+const alternates = await client.getProductAlternates(product.id);
+// → [{ locale: 'en', slug: 'cheese-pizza' }, { locale: 'he', slug: 'פיצה-גבינה' }]
+
+// In generateMetadata:
+return {
+  alternates: {
+    languages: Object.fromEntries(
+      alternates.map((a) => [a.locale, `/${a.locale}/products/${a.slug}`])
+    ),
+  },
+};
+```
+
+## Promotional surfaces: bundles, bumps, discount banners
+
+The same overlay applies to every promotional surface — you don't need locale-aware code:
+
+```tsx
+// Cart bundles (cross-sell) — locale-aware automatically:
+const cart = await client.getCart(cartId);
+cart.bundles[0].name; // "ארוחת צהריים" (bundle's own label)
+cart.bundles[0].offeredProducts[0].name; // "פיצה גבינה" (each offered product)
+
+// Order bumps at checkout:
+const { bumps } = await client.getOrderBumps(checkoutId);
+bumps[0].title; // translated bump headline (or merchant override)
+bumps[0].bumpProduct.name; // translated product name
+
+// Discount-rule banners (rendered from rule.name + rule.displayConfig):
+const rules = await client.getActiveDiscountRules();
+rules[0].name; // translated rule name
+```
+
+## How merchants populate translations
+
+For background — your storefront doesn't need to call these endpoints, but knowing the merchant flow helps when debugging unexpectedly-empty translations:
+
+- **Per-row overlay** on every taxonomy/product list page in the dashboard.
+- **Inside the entity create/edit modal** — a `LocaleSelector` in the header + "Translate with AI" button populates target-locale fields (Products, Attributes, Modifier Groups, Modifiers, Custom Fields).
+- **Translate icon button** on bundle / order-bump rows (`/products/.../offers`) and on discount-rule rows (`/discount-rules`) opens a standalone translation modal with one-click AI.
+- **Bulk** — select N rows on a list page → toolbar action "Translate to Hebrew" enqueues an AI translation job for everything selected (including children, e.g. all modifiers under selected groups).
+
+Translations are persisted via the dashboard-only endpoint `PUT /api/stores/:storeId/translations/:entityType/:entityId/:locale`. The storefront SDK never calls this — it only consumes the overlay on read.
+
+## Troubleshooting
+
+| Symptom                                                        | Likely cause                                        | Fix                                                                               |
+| -------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `product.name` is English even though locale is `he`           | Store doesn't have `he` in `supportedLocales`       | Add the locale in `Dashboard → Settings → Languages`                              |
+| Some fields translate, others don't                            | Merchant translated subset                          | Per-field fallback is by design — fill the rest in dashboard                      |
+| Layout broken in Hebrew                                        | Missing `<html dir="rtl">`                          | Use `getDirection(locale)` in the layout                                          |
+| Modifier names in default language but product name translates | Merchant translated `Product` only                  | Bulk translate on `/products/modifier-groups` covers groups + all their modifiers |
+| Custom-field label "Warranty" doesn't translate                | Merchant didn't translate the `MetafieldDefinition` | Per-row "Translate" on `/products/custom-fields`                                  |
+| Bundle name "Summer Sale" stays in English in Hebrew cart      | Merchant didn't translate the `BundleOffer` itself  | Click the Languages icon on the bundle row in `/products/.../offers`              |
+
+See [the Brainerce docs](https://brainerce.com/docs/concepts/translations) for the canonical reference.

package/templates/nextjs/base/next.config.ts

@@ -1,5 +1,27 @@
 import type { NextConfig } from 'next';
 
+// Build-time invariant — fail loud if NEXT_PUBLIC_STORE_CURRENCY is missing
+// for a production build. Next.js inlines NEXT_PUBLIC_* into the client
+// bundle at `next build` time; once inlined, the value cannot be patched at
+// deploy time. A missing env here is the root cause of non-USD stores ending
+// up with `$5,096` baked into their HTML (and indexed by Googlebot).
+//
+// In dev (`next dev`) we only warn, so local-only experiments don't break.
+if (!process.env.NEXT_PUBLIC_STORE_CURRENCY) {
+  const msg =
+    'NEXT_PUBLIC_STORE_CURRENCY is not set.\n' +
+    'Next.js inlines NEXT_PUBLIC_* vars into the client bundle at build time;\n' +
+    'a missing value will silently fall back to USD in storefront price displays\n' +
+    'and ship that to search-engine crawlers. Set it in .env.local (written by\n' +
+    'create-brainerce-store) or in your CI / hosting build env (Coolify / Vercel).';
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error(`[next.config] ${msg}`);
+  } else {
+    // eslint-disable-next-line no-console
+    console.warn(`[next.config] warning: ${msg}`);
+  }
+}
+
 const nextConfig: NextConfig = {
   // isomorphic-dompurify ships jsdom, which at runtime reads stylesheet files
   // from its own package directory. Webpack bundling breaks those relative

package/templates/nextjs/base/package.json.ejs

@@ -28,5 +28,8 @@
     "postcss": "^8.4.0",
     "tailwindcss": "^3.4.0",
     "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
   }
 }

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

@@ -38,7 +38,7 @@ function CheckoutContent() {
   const { storeInfo } = useStoreInfo();
   const { cart, refreshCart } = useCart();
   const { isLoggedIn } = useAuth();
-  const currency = storeInfo?.currency || 'USD';
+  const currency = storeInfo?.currency || process.env.NEXT_PUBLIC_STORE_CURRENCY || 'USD';
   const t = useTranslations('checkout');
   const tc = useTranslations('common');
 

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

@@ -5,7 +5,7 @@ import { StoreProvider } from '@/providers/store-provider';
 import { AnnouncementBar } from '@/components/content/announcement-bar';
 import { SiteHeader } from '@/components/content/site-header';
 import { SiteFooter } from '@/components/content/site-footer';
-import { getServerClient } from '@/lib/brainerce';
+import { getServerClient, fetchStoreInfo } from '@/lib/brainerce';
 import { getDirection, supportedLocales } from '@/i18n';
 import { getNonce } from '@/lib/nonce';
 import '../globals.css';
@@ -61,10 +61,14 @@ export default async function RootLayout({
   // seeded a particular content type yet. New stores ship with default rows
   // seeded by the backend (StoresService.seedDefaultContent).
   const client = getServerClient(locale);
-  const [announcements, siteHeader, siteFooter] = await Promise.all([
+  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
     client.content.announcement.list(locale).catch(() => []),
     client.content.header.get('main', locale).catch(() => null),
     client.content.footer.get('main', locale).catch(() => null),
+    // SSR-fetch store config so PriceDisplay / FreeShippingBar / upsell UI
+    // render with the real currency, feature flags, and i18n config at frame 0
+    // — without this, Googlebot sees USD/defaults baked into the HTML.
+    fetchStoreInfo(locale),
   ]);
 
   return (
@@ -83,7 +87,7 @@ export default async function RootLayout({
         />
       </head>
       <body className={font.className}>
-        <StoreProvider locale={locale}>
+        <StoreProvider locale={locale} initialStoreInfo={storeInfo}>
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />
@@ -102,7 +106,7 @@ import { StoreProvider } from '@/providers/store-provider';
 import { AnnouncementBar } from '@/components/content/announcement-bar';
 import { SiteHeader } from '@/components/content/site-header';
 import { SiteFooter } from '@/components/content/site-footer';
-import { getServerClient } from '@/lib/brainerce';
+import { getServerClient, fetchStoreInfo } from '@/lib/brainerce';
 import { getNonce } from '@/lib/nonce';
 import './globals.css';
 
@@ -150,10 +154,14 @@ export default async function RootLayout({
   // seeded a particular content type yet. New stores ship with default rows
   // seeded by the backend (StoresService.seedDefaultContent).
   const client = getServerClient();
-  const [announcements, siteHeader, siteFooter] = await Promise.all([
+  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
     client.content.announcement.list().catch(() => []),
     client.content.header.get('main').catch(() => null),
     client.content.footer.get('main').catch(() => null),
+    // SSR-fetch store config so PriceDisplay / FreeShippingBar / upsell UI
+    // render with the real currency, feature flags, and i18n config at frame 0
+    // — without this, Googlebot sees USD/defaults baked into the HTML.
+    fetchStoreInfo(),
   ]);
 
   return (
@@ -172,7 +180,7 @@ export default async function RootLayout({
         />
       </head>
       <body className={font.className}>
-        <StoreProvider>
+        <StoreProvider initialStoreInfo={storeInfo}>
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />

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

@@ -17,6 +17,7 @@ import { notFound } from 'next/navigation';
 
 import { getServerClient } from '@/lib/brainerce';
 import { sanitizeHtml } from '@/lib/sanitize';
+import { decodeSlug } from '@/lib/utils';
 
 <% if (i18nEnabled) { %>
 type PageProps = {
@@ -24,7 +25,8 @@ type PageProps = {
 };
 
 export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
-  const { locale, slug } = await params;
+  const { locale, slug: rawSlug } = await params;
+  const slug = decodeSlug(rawSlug);
   const page = await getServerClient(locale).content.page.getBySlug(slug, locale).catch(() => null);
   if (!page) return { title: slug };
   const seo = page.data.seo ?? {};
@@ -36,7 +38,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
 }
 
 export default async function StaticPage({ params }: PageProps) {
-  const { locale, slug } = await params;
+  const { locale, slug: rawSlug } = await params;
+  const slug = decodeSlug(rawSlug);
   const page = await getServerClient(locale).content.page.getBySlug(slug, locale).catch(() => null);
   if (!page) notFound();
   return (
@@ -57,7 +60,8 @@ type PageProps = {
 };
 
 export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
-  const { slug } = await params;
+  const { slug: rawSlug } = await params;
+  const slug = decodeSlug(rawSlug);
   const page = await getServerClient().content.page.getBySlug(slug).catch(() => null);
   if (!page) return { title: slug };
   const seo = page.data.seo ?? {};
@@ -69,7 +73,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
 }
 
 export default async function StaticPage({ params }: PageProps) {
-  const { slug } = await params;
+  const { slug: rawSlug } = await params;
+  const slug = decodeSlug(rawSlug);
   const page = await getServerClient().content.page.getBySlug(slug).catch(() => null);
   if (!page) notFound();
   return (

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

@@ -1,7 +1,9 @@
 import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
-import { getServerClient } from '@/lib/brainerce';
+import { getProductPriceInfo } from 'brainerce';
+import { getServerClient, fetchStoreInfo } from '@/lib/brainerce';
 import { buildMetaDescription } from '@/lib/seo';
+import { decodeSlug } from '@/lib/utils';
 import { ProductJsonLd } from '@/components/seo/product-json-ld';
 import { ReviewsSection } from '@/components/reviews/reviews-section';
 import { ProductClientSection } from './product-client-section';
@@ -11,11 +13,18 @@ type Props = {
 };
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { slug, locale } = await params;
+  const { slug: rawSlug, locale } = await params;
+  const slug = decodeSlug(rawSlug);
 
   try {
     const client = getServerClient(locale);
-    const product = await client.getProductBySlug(slug);
+    // Fetch product + store info in parallel; storeInfo gives us the live
+    // currency for OG price tags (with env-var + USD fallbacks so we never
+    // silently emit a wrong currency when the API is briefly unreachable).
+    const [product, storeInfo] = await Promise.all([
+      client.getProductBySlug(slug),
+      fetchStoreInfo(locale),
+    ]);
     const imageUrl = product.images?.[0]?.url;
     // Prefer merchant-authored SEO copy; fall back to a stripped+truncated
     // version of the visible description, then product name. We must NEVER
@@ -26,6 +35,16 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
       buildMetaDescription(product.description) ||
       product.name;
 
+    // OG product meta tags drive WhatsApp / Facebook / X link previews and
+    // Google Merchant Center product enrichment. Emitting the literal "0"
+    // here (the previous bug) causes price-zero link cards. Use the real
+    // effective price from the SDK helper.
+    const priceInfo = getProductPriceInfo(product);
+    const currency = storeInfo?.currency || process.env.NEXT_PUBLIC_STORE_CURRENCY || 'USD';
+    const priceAmount = priceInfo.price > 0 ? priceInfo.price.toFixed(2) : null;
+    const inStock = product.inventory?.canPurchase !== false;
+    const brandName = (product as { brand?: { name?: string } | null }).brand?.name;
+
     return {
       title: seoTitle,
       description: seoDescription,
@@ -44,6 +63,22 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
         description: seoDescription,
         images: imageUrl ? [imageUrl] : [],
       },
+      // Emit the OG product extension (Facebook / WhatsApp / X link previews,
+      // Google Merchant Center). Skips the price pair entirely when the SDK
+      // can't determine a positive amount, rather than shipping "0".
+      other: {
+        ...(priceAmount
+          ? {
+              'og:price:amount': priceAmount,
+              'og:price:currency': currency,
+              'product:price:amount': priceAmount,
+              'product:price:currency': currency,
+            }
+          : {}),
+        'product:availability': inStock ? 'in stock' : 'out of stock',
+        'product:condition': 'new',
+        ...(brandName ? { 'product:brand': brandName } : {}),
+      },
     };
   } catch {
     return {
@@ -53,7 +88,8 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
 }
 
 export default async function ProductDetailPage({ params }: Props) {
-  const { slug, locale } = await params;
+  const { slug: rawSlug, locale } = await params;
+  const slug = decodeSlug(rawSlug);
 
   let product;
   try {
@@ -65,7 +101,11 @@ export default async function ProductDetailPage({ params }: Props) {
 
   const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || '';
   const productUrl = `${baseUrl}/products/${slug}`;
-  const currency = process.env.NEXT_PUBLIC_STORE_CURRENCY || 'USD';
+  // Reuse the cached storeInfo from generateMetadata's call — React cache()
+  // collapses both into one backend request per render. Falls back to env
+  // var then USD if the server fetch returned null.
+  const storeInfo = await fetchStoreInfo(locale);
+  const currency = storeInfo?.currency || process.env.NEXT_PUBLIC_STORE_CURRENCY || 'USD';
 
   return (
     <>