create-cartbase 0.1.16 → 0.1.18

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-page-client.tsx

@@ -1,73 +1,73 @@
-"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.
+        // 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>
+  )
+}

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

@@ -1,48 +1,48 @@
-import { cookies } from "next/headers"
-import { redirect } from "next/navigation"
-import { retrieveCart } from "@cartbase/storefront/api/carts"
-import {
-  listPaymentProviders,
-  listShippingOptions,
-} from "@cartbase/storefront/api/checkout"
-import { readCartCookie } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-import { CheckoutPageClient } from "./checkout-page-client"
-
-/**
- * Checkout (runbook step 8 / checkout.md): list shipping options and
- * payment providers WITH `cart_id` (server-side rule filtering), fetch the
- * integrations `cod` block, and hand everything to the orchestrated
- * client layout. Redirect completed/missing carts server-side
- * (checkout-client mount rule).
- */
-export default async function CheckoutPage() {
-  const jar = await cookies()
-  // 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 [shippingOptions, paymentProviders] = await Promise.all([
-    listShippingOptions(client, { cart_id: cart.id }),
-    listPaymentProviders(client, {
-      cart_id: cart.id,
-      region_id: cart.region_id ?? undefined,
-    }),
-  ])
-
-  return (
-    <CheckoutPageClient
-      cart={cart}
-      shippingOptions={shippingOptions.shipping_options}
-      paymentProviders={paymentProviders.payment_providers}
-    />
-  )
-}
+import { cookies } from "next/headers"
+import { redirect } from "next/navigation"
+import { retrieveCart } from "@cartbase/storefront/api/carts"
+import {
+  listPaymentProviders,
+  listShippingOptions,
+} from "@cartbase/storefront/api/checkout"
+import { readCartCookie } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+import { CheckoutPageClient } from "./checkout-page-client"
+
+/**
+ * Checkout (runbook step 8 / checkout.md): list shipping options and
+ * payment providers WITH `cart_id` (server-side rule filtering), fetch the
+ * integrations `cod` block, and hand everything to the orchestrated
+ * client layout. Redirect completed/missing carts server-side
+ * (checkout-client mount rule).
+ */
+export default async function CheckoutPage() {
+  const jar = await cookies()
+  // 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 [shippingOptions, paymentProviders] = await Promise.all([
+    listShippingOptions(client, { cart_id: cart.id }),
+    listPaymentProviders(client, {
+      cart_id: cart.id,
+      region_id: cart.region_id ?? undefined,
+    }),
+  ])
+
+  return (
+    <CheckoutPageClient
+      cart={cart}
+      shippingOptions={shippingOptions.shipping_options}
+      paymentProviders={paymentProviders.payment_providers}
+    />
+  )
+}

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/page.tsx

@@ -1,28 +1,28 @@
-import { StoreTemplate } from "@cartbase/storefront/store/store-template"
-import type { SortOptions } from "@cartbase/storefront/lib/sort-products"
-import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-
-/**
- * Home = the all-products listing (runbook step 5: always pass a pricing
- * context or prices come back undecorated).
- */
-export default async function HomePage({
-  searchParams,
-}: {
-  searchParams: Promise<{ sortBy?: string; page?: string }>
-}) {
-  const { sortBy, page } = await searchParams
-  const client = await getServerClient()
-  return (
-    <StoreTemplate
-      client={client}
-      sortBy={sortBy as SortOptions | undefined}
-      page={page}
-      pricingContext={PRICING_CONTEXT}
-      // Server-rendered: the locale provider cannot reach it, so the pack
-      // comes as a prop, and the prop is required.
-      labels={STORE_LOCALE.store}
-    />
-  )
-}
+import { StoreTemplate } from "@cartbase/storefront/store/store-template"
+import type { SortOptions } from "@cartbase/storefront/lib/sort-products"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+
+/**
+ * Home = the all-products listing (runbook step 5: always pass a pricing
+ * context or prices come back undecorated).
+ */
+export default async function HomePage({
+  searchParams,
+}: {
+  searchParams: Promise<{ sortBy?: string; page?: string }>
+}) {
+  const { sortBy, page } = await searchParams
+  const client = await getServerClient()
+  return (
+    <StoreTemplate
+      client={client}
+      sortBy={sortBy as SortOptions | undefined}
+      page={page}
+      pricingContext={PRICING_CONTEXT}
+      // Server-rendered: the locale provider cannot reach it, so the pack
+      // comes as a prop, and the prop is required.
+      labels={STORE_LOCALE.store}
+    />
+  )
+}

package/template/app/src/app/products/[handle]/page.tsx

@@ -1,87 +1,87 @@
-import { notFound } from "next/navigation"
-import { retrieveProduct } from "@cartbase/storefront/api/products"
-import { StoreApiError } from "@cartbase/storefront/api/types"
-import { ProductTemplate } from "@cartbase/storefront/products/product-template"
-import { addToCartAction } from "@/lib/cart-actions"
-import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-
-/**
- * PDP (runbook step 5): fetch by handle WITH the pricing context, render
- * the full product template. `addToCart` is the app-owned seam — a server
- * action that owns the cart cookie (products family contract).
- */
-export default async function ProductPage({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ handle: string }>
-  searchParams: Promise<{ variant?: string }>
-}) {
-  const [{ handle }, { variant }] = await Promise.all([params, searchParams])
-  const client = await getServerClient()
-
-  let product
-  try {
-    const res = await retrieveProduct(client, handle, PRICING_CONTEXT)
-    product = res.product
-  } catch (e) {
-    if (e instanceof StoreApiError && e.status === 404) notFound()
-    throw e
-  }
-
-  return (
-    <ProductTemplate
-      client={client}
-      product={product}
-      pricingContext={PRICING_CONTEXT}
-      addToCart={addToCartAction}
-      // The product page contract: the address names the variant
-      // (`?variant=<digits>`, Shopify's parameter), and the page hands it to
-      // the template so the FIRST paint is that variant's price, code and
-      // stock. Switching a variant rewrites the address in the browser
-      // without asking the server.
-      initialVariantId={variant}
-      // NO `promises` here, deliberately. Until 0.13.0 the library carried
-      // delivery, exchange and return promises as label DEFAULTS, so every
-      // store scaffolded from this file told shoppers "your package will
-      // arrive in 3-5 business days" and "we'll refund your money" without
-      // anyone having decided that. Those are YOUR commitments, so you write
-      // them:
-      //
-      //   promises={[
-      //     { icon: "delivery", title: "Fast delivery",
-      //       body: "Your order arrives in 2 working days." },
-      //   ]}
-      //
-      // Pass nothing and the section does not exist, which is the right
-      // default for a store that has not decided yet. The physical-facts
-      // section appears on its own for products that HAVE facts, and is
-      // skipped for those that do not.
-      //
-      // The pack has to be handed over here, not just mounted at the root:
-      // the related-products strip is a server component and cannot read
-      // the locale provider, so its heading would stay English. Required.
-      labels={STORE_LOCALE.products}
-    />
-  )
-}
-
-export async function generateMetadata({
-  params,
-}: {
-  params: Promise<{ handle: string }>
-}) {
-  const { handle } = await params
-  const client = await getServerClient()
-  try {
-    const { product } = await retrieveProduct(client, handle)
-    // SEO fields with title/description fallbacks (runbook step 5).
-    return {
-      title: product.seo_title ?? product.title,
-      description: product.seo_description ?? product.description ?? undefined,
-    }
-  } catch {
-    return {}
-  }
-}
+import { notFound } from "next/navigation"
+import { retrieveProduct } from "@cartbase/storefront/api/products"
+import { StoreApiError } from "@cartbase/storefront/api/types"
+import { ProductTemplate } from "@cartbase/storefront/products/product-template"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+
+/**
+ * PDP (runbook step 5): fetch by handle WITH the pricing context, render
+ * the full product template. No `addToCart` is passed: the add goes
+ * through the cart drawer mounted in `providers.tsx`, so the drawer opens
+ * at the click with the product in it and no page render runs (the product
+ * page contract, rule 6). The drawer's `onCartChange` owns the cart cookie.
+ */
+export default async function ProductPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ handle: string }>
+  searchParams: Promise<{ variant?: string }>
+}) {
+  const [{ handle }, { variant }] = await Promise.all([params, searchParams])
+  const client = await getServerClient()
+
+  let product
+  try {
+    const res = await retrieveProduct(client, handle, PRICING_CONTEXT)
+    product = res.product
+  } catch (e) {
+    if (e instanceof StoreApiError && e.status === 404) notFound()
+    throw e
+  }
+
+  return (
+    <ProductTemplate
+      client={client}
+      product={product}
+      pricingContext={PRICING_CONTEXT}
+      // The product page contract: the address names the variant
+      // (`?variant=<digits>`, Shopify's parameter), and the page hands it to
+      // the template so the FIRST paint is that variant's price, code and
+      // stock. Switching a variant rewrites the address in the browser
+      // without asking the server.
+      initialVariantId={variant}
+      // NO `promises` here, deliberately. Until 0.13.0 the library carried
+      // delivery, exchange and return promises as label DEFAULTS, so every
+      // store scaffolded from this file told shoppers "your package will
+      // arrive in 3-5 business days" and "we'll refund your money" without
+      // anyone having decided that. Those are YOUR commitments, so you write
+      // them:
+      //
+      //   promises={[
+      //     { icon: "delivery", title: "Fast delivery",
+      //       body: "Your order arrives in 2 working days." },
+      //   ]}
+      //
+      // Pass nothing and the section does not exist, which is the right
+      // default for a store that has not decided yet. The physical-facts
+      // section appears on its own for products that HAVE facts, and is
+      // skipped for those that do not.
+      //
+      // The pack has to be handed over here, not just mounted at the root:
+      // the related-products strip is a server component and cannot read
+      // the locale provider, so its heading would stay English. Required.
+      labels={STORE_LOCALE.products}
+    />
+  )
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ handle: string }>
+}) {
+  const { handle } = await params
+  const client = await getServerClient()
+  try {
+    const { product } = await retrieveProduct(client, handle)
+    // SEO fields with title/description fallbacks (runbook step 5).
+    return {
+      title: product.seo_title ?? product.title,
+      description: product.seo_description ?? product.description ?? undefined,
+    }
+  } catch {
+    return {}
+  }
+}