create-cartbase 0.1.20 → 0.1.22

package/template/app/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.20.0",
+    "@cartbase/storefront": "^0.22.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/postcss.config.cjs

@@ -1,11 +1,11 @@
-/*
- * Tailwind 4 ships its own PostCSS plugin and handles vendor prefixing
- * internally, so the v3 pairing of `tailwindcss` + `autoprefixer` is gone.
- * There is no tailwind.config file either: the theme is defined in CSS
- * (see src/app/globals.css and the theme shipped by @cartbase/storefront).
- */
-module.exports = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
-}
+/*
+ * Tailwind 4 ships its own PostCSS plugin and handles vendor prefixing
+ * internally, so the v3 pairing of `tailwindcss` + `autoprefixer` is gone.
+ * There is no tailwind.config file either: the theme is defined in CSS
+ * (see src/app/globals.css and the theme shipped by @cartbase/storefront).
+ */
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+}

package/template/app/src/app/checkout/checkout-empty.tsx

@@ -0,0 +1,36 @@
+import Link from "next/link"
+import { defaultCheckoutLabels } from "@cartbase/storefront/checkout/labels"
+
+/**
+ * The checkout with nothing to check out.
+ *
+ * A shopper who lands here with an empty cart used to be redirected to the
+ * home page without a word, which reads as the store losing their order.
+ * The page says it instead and offers the way back, which matters more here
+ * than anywhere: a checkout shell carries no header and no cart drawer, so
+ * the notice is the only door.
+ *
+ * The copy is the label pack's, so a store that mounts a locale gets it in
+ * its own language; this route renders on the server, above the provider,
+ * so it reads the defaults directly.
+ */
+export function CheckoutEmpty() {
+  const labels = defaultCheckoutLabels
+
+  return (
+    <div className="mx-auto flex max-w-md flex-col items-center px-5 py-20 text-center">
+      <h1 className="text-xl font-semibold text-foreground">
+        {labels.cartEmptyTitle}
+      </h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        {labels.cartEmptyText}
+      </p>
+      <Link
+        href="/"
+        className="mt-6 inline-flex h-12 items-center justify-center rounded-xl bg-foreground px-8 text-sm font-semibold text-card transition-colors hover:bg-foreground/90"
+      >
+        {labels.cartEmptyBack}
+      </Link>
+    </div>
+  )
+}

package/template/app/src/app/checkout/checkout-page-client.tsx

@@ -1,73 +1,80 @@
-"use client"
-
-import { useRouter } from "next/navigation"
-import type { Cart } from "@cartbase/storefront/api/carts"
-import type { StoreShippingOption } from "@cartbase/storefront/api/checkout"
-import type { StorePaymentEntry } from "@cartbase/storefront/api/checkout"
-import { CheckoutProvider } from "@cartbase/storefront/checkout/context"
-import { CheckoutClient } from "@cartbase/storefront/checkout/checkout-client"
-import { browserClient } from "@/lib/browser-client"
-
-/** sessionStorage key the confirmation page reads (guests have no order
- * read endpoint — the completeCart() response is the only order handle,
- * orders.md). */
-export const LAST_ORDER_STORAGE_KEY = "barter:last-order"
-
-export function CheckoutPageClient({
-  cart,
-  shippingOptions,
-  paymentProviders,
-}: {
-  cart: Cart
-  shippingOptions: StoreShippingOption[]
-  paymentProviders: StorePaymentEntry[]
-}) {
-  const router = useRouter()
-
-  return (
-    <CheckoutProvider orderConfirmedPath="/order/{id}/confirmed">
-      <CheckoutClient
-        client={browserClient}
-        cart={cart}
-        customer={null}
-        availableShippingMethods={shippingOptions}
-        availablePaymentMethods={paymentProviders}
-        // NO COUNTRY LIST HERE, on purpose (2026-09-13). This file is the
-        // seed for every scaffolded store, and it used to pass
-        // `countries={[{iso_2:"bg", display_name:"Bulgaria"}]}` with
-        // `countryCode="bg"`, so every store on earth shipped a checkout
-        // offering one country, Bulgaria, in a box the shopper could not
-        // change. The list belongs to the store, not to this file: omit the
-        // prop and the hook reads GET /api/store/countries, which answers
-        // with the countries the store's Markets declare, or with the whole
-        // world when it has declared none.
-        //
-        // A single-market store adds `countryCode="xx"` here to preselect
-        // its country, and a store that sells to exactly one country gets
-        // the read-only field automatically, because its Markets say so.
-        // Per-store rule (the documented paymentMethodFilter seam): this
-        // reference store checks out offline via its merchant methods only
-        // (pp_* kill: method entries carry payment_method_id, processors
-        // carry id) — the filter drops any connected processor.
-        paymentMethodFilter={(methods) =>
-          methods?.filter((m) => "payment_method_id" in m) ?? null
-        }
-        onOrderPlaced={(order) => {
-          // Guest order handle = the completeCart() response (orders.md).
-          // Stash it (+ the decorated cart lines for the items list) for
-          // the confirmation page, then navigate.
-          try {
-            sessionStorage.setItem(
-              LAST_ORDER_STORAGE_KEY,
-              JSON.stringify({ order, cartItems: cart.items ?? [] })
-            )
-          } catch {
-            // best-effort — the confirmation page has a fallback state
-          }
-          router.push(`/order/${order.id}/confirmed`)
-        }}
-        onCartChange={() => router.refresh()}
-      />
-    </CheckoutProvider>
-  )
-}
+"use client"
+
+import { useRouter } from "next/navigation"
+import type { Cart } from "@cartbase/storefront/api/carts"
+import type { StoreShippingOption } from "@cartbase/storefront/api/checkout"
+import type { StorePaymentEntry } from "@cartbase/storefront/api/checkout"
+import { CheckoutProvider } from "@cartbase/storefront/checkout/context"
+import { CheckoutClient } from "@cartbase/storefront/checkout/checkout-client"
+import { browserClient } from "@/lib/browser-client"
+
+/** sessionStorage key the confirmation page reads (guests have no order
+ * read endpoint — the completeCart() response is the only order handle,
+ * orders.md). */
+export const LAST_ORDER_STORAGE_KEY = "barter:last-order"
+
+export function CheckoutPageClient({
+  cart,
+  shippingOptions,
+  paymentProviders,
+}: {
+  cart: Cart
+  shippingOptions: StoreShippingOption[]
+  paymentProviders: StorePaymentEntry[]
+}) {
+  const router = useRouter()
+
+  return (
+    <CheckoutProvider orderConfirmedPath="/order/{id}/confirmed">
+      <CheckoutClient
+        client={browserClient}
+        cart={cart}
+        customer={null}
+        availableShippingMethods={shippingOptions}
+        availablePaymentMethods={paymentProviders}
+        // NO COUNTRY LIST HERE, on purpose (2026-09-13). This file is the
+        // seed for every scaffolded store, and it used to pass
+        // `countries={[{iso_2:"bg", display_name:"Bulgaria"}]}` with
+        // `countryCode="bg"`, so every store on earth shipped a checkout
+        // offering one country, Bulgaria, in a box the shopper could not
+        // change. The list belongs to the store, not to this file: omit the
+        // prop and the hook reads GET /api/store/countries, which answers
+        // with the countries the store's Markets declare, or with the whole
+        // world when it has declared none.
+        //
+        // A single-market store adds `countryCode="xx"` here to preselect
+        // its country, and a store that sells to exactly one country gets
+        // the read-only field automatically, because its Markets say so.
+        //
+        // NO PAYMENT FILTER HERE, on purpose (2026-09-18), for the same
+        // reason as the country list. This file used to pass a
+        // `paymentMethodFilter` that kept merchant methods and dropped every
+        // connected processor, so every scaffolded store was born ignoring
+        // its own card: a merchant could connect Stripe in the admin, see it
+        // reported as connected, and still be offered nothing but cash on
+        // delivery at checkout, with no error anywhere to explain it. What a
+        // store can be paid with is the store's answer, and the listing
+        // already gives it: processors it has connected and linked to the
+        // market, plus its enabled methods, rule-filtered server-side. The
+        // `paymentMethodFilter` seam stays for a store with a real reason to
+        // narrow it further, and a store with no processor connected needs
+        // no filter to hide one.
+        onOrderPlaced={(order) => {
+          // Guest order handle = the completeCart() response (orders.md).
+          // Stash it (+ the decorated cart lines for the items list) for
+          // the confirmation page, then navigate.
+          try {
+            sessionStorage.setItem(
+              LAST_ORDER_STORAGE_KEY,
+              JSON.stringify({ order, cartItems: cart.items ?? [] })
+            )
+          } catch {
+            // best-effort — the confirmation page has a fallback state
+          }
+          router.push(`/order/${order.id}/confirmed`)
+        }}
+        onCartChange={() => router.refresh()}
+      />
+    </CheckoutProvider>
+  )
+}

package/template/app/src/app/checkout/error.tsx

@@ -0,0 +1,23 @@
+"use client"
+
+import { CheckoutErrorScreen } from "@cartbase/storefront/checkout/checkout-error-screen"
+import { browserClient } from "@/lib/browser-client"
+
+/**
+ * The checkout's error boundary. Next renders this in place of the page
+ * when anything in it throws, a server component included, so a shopper at
+ * the moment of paying sees the store's own words instead of the
+ * framework's error page, and the failure reaches the merchant's checkout
+ * error log rather than nobody.
+ */
+export default function CheckoutError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    <CheckoutErrorScreen error={error} reset={reset} client={browserClient} />
+  )
+}

package/template/app/src/app/checkout/page.tsx

@@ -8,6 +8,7 @@ import {
 } from "@cartbase/storefront/api/checkout"
 import { readCartCookie } from "@/lib/config"
 import { getServerClient } from "@/lib/server-client"
+import { CheckoutEmpty } from "./checkout-empty"
 import { CheckoutPageClient } from "./checkout-page-client"
 
 /**
@@ -32,14 +33,22 @@ async function Checkout() {
   // Back-compat: prefer `_cartbase_cart`, fall back to the legacy
   // `_barter_cart_id` name (platform-fingerprints card).
   const cartId = readCartCookie((name) => jar.get(name)?.value)
-  if (!cartId) redirect("/")
 
-  const client = await getServerClient()
-  const cart = await retrieveCart(client, cartId)
-    .then((res) => res.cart)
-    .catch(() => null)
-  if (!cart || (cart.items ?? []).length === 0) redirect("/")
-  if (cart.completed_at) redirect("/")
+  const client = cartId ? await getServerClient() : null
+  const cart =
+    client && cartId
+      ? await retrieveCart(client, cartId)
+          .then((res) => res.cart)
+          .catch(() => null)
+      : null
+
+  // A placed order still redirects: it has its own confirmation page.
+  if (cart?.completed_at) redirect("/")
+
+  // Nothing to check out, so the page SAYS so rather than bouncing the
+  // shopper home without a word (2026-09-18). A checkout shell carries no
+  // header and no drawer, so this notice is also the only way back.
+  if (!client || !cart || (cart.items ?? []).length === 0) return <CheckoutEmpty />
 
   const [shippingOptions, paymentProviders] = await Promise.all([
     listShippingOptions(client, { cart_id: cart.id }),

package/template/app/src/app/globals.css

@@ -1,26 +1,26 @@
-/*
- * The whole styling setup for a Cartbase storefront: two imports.
- *
- * Tailwind 4 is CSS-first, so there is no config file and no preset to
- * register. The library ships its theme filled, so this app renders as a
- * designed store without choosing a single value.
- *
- * To make the store yours, override the token values below the imports.
- * Never redefine the names — components reference them, and the library
- * repaints from the values alone.
- */
-@import "tailwindcss";
-@import "@cartbase/storefront/theme";
-
-/*
- * The library ships as TypeScript source rather than a build, so Tailwind has
- * to scan it to know which classes exist. Without this the components render
- * with no styles at all — the classes are in the markup but never generated.
- */
-@source "../../node_modules/@cartbase/storefront/src";
-
-/*
- * Dark mode is class-based: put `.dark` on <html> and every token swaps.
- * Tailwind 4 needs this declared explicitly.
- */
-@custom-variant dark (&:where(.dark, .dark *));
+/*
+ * The whole styling setup for a Cartbase storefront: two imports.
+ *
+ * Tailwind 4 is CSS-first, so there is no config file and no preset to
+ * register. The library ships its theme filled, so this app renders as a
+ * designed store without choosing a single value.
+ *
+ * To make the store yours, override the token values below the imports.
+ * Never redefine the names — components reference them, and the library
+ * repaints from the values alone.
+ */
+@import "tailwindcss";
+@import "@cartbase/storefront/theme";
+
+/*
+ * The library ships as TypeScript source rather than a build, so Tailwind has
+ * to scan it to know which classes exist. Without this the components render
+ * with no styles at all — the classes are in the markup but never generated.
+ */
+@source "../../node_modules/@cartbase/storefront/src";
+
+/*
+ * Dark mode is class-based: put `.dark` on <html> and every token swaps.
+ * Tailwind 4 needs this declared explicitly.
+ */
+@custom-variant dark (&:where(.dark, .dark *));

package/template/app/src/app/layout.tsx

@@ -1,126 +1,126 @@
-import type { Metadata } from "next"
-import Link from "next/link"
-import type { Menu } from "@cartbase/storefront/api/menus"
-import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
-import { StorefrontTags } from "@cartbase/storefront/tracking/storefront-tags"
-import { TrackInit } from "@cartbase/storefront/tracking/track-init"
-import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
-import { createStorefrontMetadata, PlatformInit } from "@cartbase/storefront/platform"
-import { STORE_LOCALE } from "@/lib/config"
-import { getConsentSettings, getMenuSafe, getStoreIdentity, getTracking } from "@/lib/catalog"
-import { Providers } from "./providers"
-import "./globals.css"
-
-// createStorefrontMetadata (platform-fingerprints card) stamps
-// `<meta name="generator" content="Cartbase" />` on every page — never
-// hand-write `generator` here.
-export async function generateMetadata(): Promise<Metadata> {
-  const store = await getStoreIdentity()
-  return createStorefrontMetadata({
-    title: store.name,
-    description: store.brand.slogan ?? undefined,
-  })
-}
-
-function MenuNav({ menu }: { menu: Menu | null }) {
-  if (!menu || menu.items.length === 0) return null
-  return (
-    <nav className="flex items-center gap-4">
-      {menu.items.map((item) => (
-        <Link
-          key={`${item.title}-${item.url}`}
-          href={item.url}
-          className="text-sm text-muted-foreground hover:text-foreground"
-        >
-          {item.title}
-        </Link>
-      ))}
-    </nav>
-  )
-}
-
-/**
- * Runbook steps 3–4: bootstrap store config at layout level, then mount
- * order inside <body>: ConsentInit FIRST (static, synchronous), then the
- * consent-gated UI, then navigation. A store with no menus 404s every
- * handle — render no nav, never crash (menus.md).
- *
- * Nothing here reads the request. The store, the consent settings, the tags
- * and the menus are cached reads (lib/catalog.ts), so the shell is
- * prerendered and every page is served from the CDN (Cache Components). The
- * cart is the visitor's: the drawer reads its id from the cookie in the
- * browser and the cart after it (providers.tsx), and the cart button counts
- * the drawer's cart, so no page waits for the cart.
- */
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  const [store, consent, tracking, mainMenu, footerMenu] = await Promise.all([
-    getStoreIdentity(),
-    getConsentSettings(),
-    getTracking(),
-    getMenuSafe("main-menu"),
-    getMenuSafe("footer"),
-  ])
-
-  return (
-    <html lang={STORE_LOCALE.code}>
-      <body>
-        {/* The store's own consent switch decides the default: a store
-            that collects consent starts every visitor denied until they
-            choose, a store with the banner off starts them granted. The
-            prop is required, so a layout cannot leave it out. */}
-        <ConsentInit required={consent.enabled} />
-        {/* Every marketing tag the store configured in the admin, mounted
-            from its own config: Meta, TikTok, ChatGPT, Google (GA4 + Ads
-            on one tag), GTM. Nothing to wire per vendor: saving the ids
-            under Settings, Integrations is the whole merchant-side act.
-            Order matters: ConsentInit sets the Consent Mode defaults
-            synchronously ABOVE this, so every tag below inherits the
-            gate. The config is a cached read handed over, so the tags
-            cost the page nothing at request time. */}
-        {tracking ? <StorefrontTags config={tracking} /> : null}
-        {/* Captures UTMs and the ad-click ids (ttclid / gclid / gbraid /
-            wbraid) that exist ONLY on an ad's landing URL — miss them
-            here and no platform can attribute the order to the click. */}
-        <TrackInit />
-        <PlatformInit storeId={store.id} />
-        <Providers consent={consent}>
-          <header className="border-b border-border">
-            <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
-              <Link href="/" className="font-semibold text-lg">
-                {store.name}
-              </Link>
-              <div className="flex items-center gap-6">
-                <MenuNav menu={mainMenu} />
-                <Link
-                  href="/search"
-                  className="text-sm text-muted-foreground hover:text-foreground"
-                >
-                  Search
-                </Link>
-                {/*
-                  The component workbench lives at /gallery in THIS app only
-                  (the seed excludes it, src/lib/storefront/seed.ts), so the
-                  shop's own nav never links to it: a merchant's store must
-                  not carry a dead link.
-                */}
-                {/* No `cart` prop: the badge counts the drawer's own cart. */}
-                <CartButtonClient />
-              </div>
-            </div>
-          </header>
-          <main>{children}</main>
-          <footer className="border-t border-border mt-12">
-            <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
-              <span>{store.name}</span>
-              <MenuNav menu={footerMenu} />
-            </div>
-          </footer>
-        </Providers>
-      </body>
-    </html>
-  )
-}
+import type { Metadata } from "next"
+import Link from "next/link"
+import type { Menu } from "@cartbase/storefront/api/menus"
+import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
+import { StorefrontTags } from "@cartbase/storefront/tracking/storefront-tags"
+import { TrackInit } from "@cartbase/storefront/tracking/track-init"
+import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
+import { createStorefrontMetadata, PlatformInit } from "@cartbase/storefront/platform"
+import { STORE_LOCALE } from "@/lib/config"
+import { getConsentSettings, getMenuSafe, getStoreIdentity, getTracking } from "@/lib/catalog"
+import { Providers } from "./providers"
+import "./globals.css"
+
+// createStorefrontMetadata (platform-fingerprints card) stamps
+// `<meta name="generator" content="Cartbase" />` on every page — never
+// hand-write `generator` here.
+export async function generateMetadata(): Promise<Metadata> {
+  const store = await getStoreIdentity()
+  return createStorefrontMetadata({
+    title: store.name,
+    description: store.brand.slogan ?? undefined,
+  })
+}
+
+function MenuNav({ menu }: { menu: Menu | null }) {
+  if (!menu || menu.items.length === 0) return null
+  return (
+    <nav className="flex items-center gap-4">
+      {menu.items.map((item) => (
+        <Link
+          key={`${item.title}-${item.url}`}
+          href={item.url}
+          className="text-sm text-muted-foreground hover:text-foreground"
+        >
+          {item.title}
+        </Link>
+      ))}
+    </nav>
+  )
+}
+
+/**
+ * Runbook steps 3–4: bootstrap store config at layout level, then mount
+ * order inside <body>: ConsentInit FIRST (static, synchronous), then the
+ * consent-gated UI, then navigation. A store with no menus 404s every
+ * handle — render no nav, never crash (menus.md).
+ *
+ * Nothing here reads the request. The store, the consent settings, the tags
+ * and the menus are cached reads (lib/catalog.ts), so the shell is
+ * prerendered and every page is served from the CDN (Cache Components). The
+ * cart is the visitor's: the drawer reads its id from the cookie in the
+ * browser and the cart after it (providers.tsx), and the cart button counts
+ * the drawer's cart, so no page waits for the cart.
+ */
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const [store, consent, tracking, mainMenu, footerMenu] = await Promise.all([
+    getStoreIdentity(),
+    getConsentSettings(),
+    getTracking(),
+    getMenuSafe("main-menu"),
+    getMenuSafe("footer"),
+  ])
+
+  return (
+    <html lang={STORE_LOCALE.code}>
+      <body>
+        {/* The store's own consent switch decides the default: a store
+            that collects consent starts every visitor denied until they
+            choose, a store with the banner off starts them granted. The
+            prop is required, so a layout cannot leave it out. */}
+        <ConsentInit required={consent.enabled} />
+        {/* Every marketing tag the store configured in the admin, mounted
+            from its own config: Meta, TikTok, ChatGPT, Google (GA4 + Ads
+            on one tag), GTM. Nothing to wire per vendor: saving the ids
+            under Settings, Integrations is the whole merchant-side act.
+            Order matters: ConsentInit sets the Consent Mode defaults
+            synchronously ABOVE this, so every tag below inherits the
+            gate. The config is a cached read handed over, so the tags
+            cost the page nothing at request time. */}
+        {tracking ? <StorefrontTags config={tracking} /> : null}
+        {/* Captures UTMs and the ad-click ids (ttclid / gclid / gbraid /
+            wbraid) that exist ONLY on an ad's landing URL — miss them
+            here and no platform can attribute the order to the click. */}
+        <TrackInit />
+        <PlatformInit storeId={store.id} />
+        <Providers consent={consent}>
+          <header className="border-b border-border">
+            <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
+              <Link href="/" className="font-semibold text-lg">
+                {store.name}
+              </Link>
+              <div className="flex items-center gap-6">
+                <MenuNav menu={mainMenu} />
+                <Link
+                  href="/search"
+                  className="text-sm text-muted-foreground hover:text-foreground"
+                >
+                  Search
+                </Link>
+                {/*
+                  The component workbench lives at /gallery in THIS app only
+                  (the seed excludes it, src/lib/storefront/seed.ts), so the
+                  shop's own nav never links to it: a merchant's store must
+                  not carry a dead link.
+                */}
+                {/* No `cart` prop: the badge counts the drawer's own cart. */}
+                <CartButtonClient />
+              </div>
+            </div>
+          </header>
+          <main>{children}</main>
+          <footer className="border-t border-border mt-12">
+            <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
+              <span>{store.name}</span>
+              <MenuNav menu={footerMenu} />
+            </div>
+          </footer>
+        </Providers>
+      </body>
+    </html>
+  )
+}