@forgecart/cli 1.1.0 → 2.0.0

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

@@ -0,0 +1,96 @@
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+
+import { AddToCartButton } from '../../../components/AddToCartButton';
+import { formatPrice, getProductBySlug } from '../../../lib/forgecart';
+
+export const dynamic = 'force-dynamic';
+
+// Next.js 15: route params are delivered as a Promise.
+export default async function ProductDetailPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const product = await getProductBySlug(slug);
+
+  if (!product) {
+    notFound();
+  }
+
+  const defaultVariant = product.variants[0] ?? null;
+
+  return (
+    <div className="space-y-6">
+      <Link href="/products" className="text-sm text-gray-600 hover:text-gray-900">
+        &larr; Back to products
+      </Link>
+
+      <div className="grid gap-8 md:grid-cols-2">
+        <div className="aspect-square overflow-hidden rounded-lg border border-gray-200 bg-gray-100">
+          {product.featuredAsset ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={product.featuredAsset.preview}
+              alt={product.name}
+              className="h-full w-full object-cover"
+            />
+          ) : (
+            <div className="flex h-full w-full items-center justify-center text-sm text-gray-400">
+              No image
+            </div>
+          )}
+        </div>
+
+        <div className="space-y-4">
+          <h1 className="text-2xl font-bold tracking-tight text-gray-900">
+            {product.name}
+          </h1>
+
+          {defaultVariant && (
+            <p className="text-xl font-semibold text-gray-900">
+              {formatPrice(defaultVariant.priceWithTax)}
+            </p>
+          )}
+
+          {product.description && (
+            <div
+              className="prose prose-sm max-w-none text-gray-600"
+              // Product descriptions may contain rich text from the dashboard.
+              dangerouslySetInnerHTML={{ __html: product.description }}
+            />
+          )}
+
+          {defaultVariant ? (
+            <AddToCartButton
+              line={{
+                variantId: defaultVariant.id,
+                productSlug: product.slug,
+                name: product.name,
+                unitPrice: defaultVariant.priceWithTax,
+                imageUrl: product.featuredAsset?.preview ?? null,
+              }}
+            />
+          ) : (
+            <p className="text-sm text-gray-500">Currently unavailable.</p>
+          )}
+
+          {product.variants.length > 1 && (
+            <div className="pt-2">
+              <h2 className="mb-2 text-sm font-medium text-gray-700">Variants</h2>
+              <ul className="space-y-1 text-sm text-gray-600">
+                {product.variants.map((variant) => (
+                  <li key={variant.id} className="flex justify-between gap-4">
+                    <span>{variant.name}</span>
+                    <span>{formatPrice(variant.priceWithTax)}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/storefront/src/app/products/page.tsx

@@ -0,0 +1,27 @@
+import { ProductCard } from '../../components/ProductCard';
+import { getProducts } from '../../lib/forgecart';
+
+export const dynamic = 'force-dynamic';
+
+export default async function ProductsPage() {
+  const { items, totalItems } = await getProducts({ take: 24 });
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-baseline justify-between">
+        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Products</h1>
+        <span className="text-sm text-gray-500">{totalItems} items</span>
+      </div>
+
+      {items.length === 0 ? (
+        <p className="text-gray-500">No products yet. Add some in your dashboard.</p>
+      ) : (
+        <div className="grid grid-cols-2 gap-6 sm:grid-cols-3 lg:grid-cols-4">
+          {items.map((product) => (
+            <ProductCard key={product.id} product={product} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/storefront/src/components/AddToCartButton.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useState } from 'react';
+
+import { useCart, type CartLine } from '../lib/cart-context';
+
+/**
+ * Adds a specific variant to the local cart. Rendered on the product detail
+ * page (a Server Component) with the variant's display data passed in as props.
+ */
+export function AddToCartButton({ line }: { line: Omit<CartLine, 'quantity'> }) {
+  const { addLine } = useCart();
+  const [added, setAdded] = useState(false);
+
+  const onClick = () => {
+    addLine(line, 1);
+    setAdded(true);
+    window.setTimeout(() => setAdded(false), 1500);
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
+    >
+      {added ? 'Added!' : 'Add to cart'}
+    </button>
+  );
+}

package/templates/storefront/src/components/Header.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import Link from 'next/link';
+
+import { useCart } from '../lib/cart-context';
+
+/** Top navigation: Home / Products / Cart, with a live cart item count. */
+export function Header() {
+  const { itemCount } = useCart();
+
+  return (
+    <header className="border-b border-gray-200 bg-white">
+      <div className="mx-auto flex max-w-6xl items-center justify-between px-4 py-4">
+        <Link href="/" className="text-lg font-bold tracking-tight text-gray-900">
+          Storefront
+        </Link>
+        <nav className="flex items-center gap-6 text-sm font-medium text-gray-600">
+          <Link href="/" className="hover:text-gray-900">
+            Home
+          </Link>
+          <Link href="/products" className="hover:text-gray-900">
+            Products
+          </Link>
+          <Link href="/cart" className="relative hover:text-gray-900">
+            Cart
+            {itemCount > 0 && (
+              <span className="ml-1 inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-gray-900 px-1.5 text-xs font-semibold text-white">
+                {itemCount}
+              </span>
+            )}
+          </Link>
+        </nav>
+      </div>
+    </header>
+  );
+}

package/templates/storefront/src/components/ProductCard.tsx

@@ -0,0 +1,43 @@
+import Link from 'next/link';
+
+import {
+  formatPrice,
+  getStartingPrice,
+  type StorefrontProduct,
+} from '../lib/forgecart';
+
+/** A product tile linking to its detail page. Used by the home and grid pages. */
+export function ProductCard({ product }: { product: StorefrontProduct }) {
+  const startingPrice = getStartingPrice(product);
+
+  return (
+    <Link
+      href={`/products/${product.slug}`}
+      className="group flex flex-col overflow-hidden rounded-lg border border-gray-200 bg-white transition hover:shadow-md"
+    >
+      <div className="aspect-square overflow-hidden bg-gray-100">
+        {product.featuredAsset ? (
+          // Plain <img> keeps the template dependency-free of next/image config.
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={product.featuredAsset.preview}
+            alt={product.name}
+            className="h-full w-full object-cover transition group-hover:scale-105"
+          />
+        ) : (
+          <div className="flex h-full w-full items-center justify-center text-sm text-gray-400">
+            No image
+          </div>
+        )}
+      </div>
+      <div className="flex flex-1 flex-col gap-1 p-4">
+        <h3 className="font-medium text-gray-900">{product.name}</h3>
+        {startingPrice !== null && (
+          <p className="text-sm text-gray-600">
+            From {formatPrice(startingPrice)}
+          </p>
+        )}
+      </div>
+    </Link>
+  );
+}

package/templates/storefront/src/lib/cart-context.tsx

@@ -0,0 +1,116 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+
+/**
+ * A line in the local cart. The MVP cart lives entirely in the browser
+ * (localStorage); wiring it to the ForgeCart `cart` API is left as a follow-up.
+ * `unitPrice` is in minor currency units (cents).
+ */
+export interface CartLine {
+  variantId: string;
+  productSlug: string;
+  name: string;
+  unitPrice: number;
+  quantity: number;
+  imageUrl: string | null;
+}
+
+interface CartContextValue {
+  lines: CartLine[];
+  itemCount: number;
+  subtotal: number;
+  addLine: (line: Omit<CartLine, 'quantity'>, quantity?: number) => void;
+  setQuantity: (variantId: string, quantity: number) => void;
+  removeLine: (variantId: string) => void;
+  clear: () => void;
+}
+
+const STORAGE_KEY = 'forgecart.cart';
+
+const CartContext = createContext<CartContextValue | null>(null);
+
+function readStoredLines(): CartLine[] {
+  if (typeof window === 'undefined') {
+    return [];
+  }
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as CartLine[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function CartProvider({ children }: { children: ReactNode }) {
+  const [lines, setLines] = useState<CartLine[]>([]);
+
+  // Hydrate from localStorage once on mount (avoids SSR hydration mismatch).
+  useEffect(() => {
+    setLines(readStoredLines());
+  }, []);
+
+  // Persist on every change.
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(lines));
+  }, [lines]);
+
+  const addLine = useCallback(
+    (line: Omit<CartLine, 'quantity'>, quantity = 1) => {
+      setLines((prev) => {
+        const existing = prev.find((l) => l.variantId === line.variantId);
+        if (existing) {
+          return prev.map((l) =>
+            l.variantId === line.variantId
+              ? { ...l, quantity: l.quantity + quantity }
+              : l,
+          );
+        }
+        return [...prev, { ...line, quantity }];
+      });
+    },
+    [],
+  );
+
+  const setQuantity = useCallback((variantId: string, quantity: number) => {
+    setLines((prev) =>
+      quantity <= 0
+        ? prev.filter((l) => l.variantId !== variantId)
+        : prev.map((l) => (l.variantId === variantId ? { ...l, quantity } : l)),
+    );
+  }, []);
+
+  const removeLine = useCallback((variantId: string) => {
+    setLines((prev) => prev.filter((l) => l.variantId !== variantId));
+  }, []);
+
+  const clear = useCallback(() => setLines([]), []);
+
+  const value = useMemo<CartContextValue>(() => {
+    const itemCount = lines.reduce((sum, l) => sum + l.quantity, 0);
+    const subtotal = lines.reduce((sum, l) => sum + l.unitPrice * l.quantity, 0);
+    return { lines, itemCount, subtotal, addLine, setQuantity, removeLine, clear };
+  }, [lines, addLine, setQuantity, removeLine, clear]);
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+/** Access the cart. Must be used inside a `<CartProvider>`. */
+export function useCart(): CartContextValue {
+  const ctx = useContext(CartContext);
+  if (!ctx) {
+    throw new Error('useCart must be used within a CartProvider');
+  }
+  return ctx;
+}

package/templates/storefront/src/lib/forgecart.ts

@@ -0,0 +1,202 @@
+import { ForgeCartShopClient } from '@forgecart/sdk';
+
+/**
+ * Server-side ForgeCart shop client.
+ *
+ * The storefront talks to the ForgeCart shop GraphQL API on behalf of a single
+ * channel. The channel token is sent as the `forgecart-token` header on every
+ * request (the SDK adds it from `channelToken`), and the endpoint points at the
+ * channel's shop-api.
+ *
+ * Both values come from the environment (`.env.local`, written by
+ * `forgecart init`):
+ *   - FORGECART_SHOP_API_URL  -> endpoint
+ *   - FORGECART_CHANNEL_TOKEN -> channelToken
+ *
+ * This module is server-only: it is imported exclusively from Server
+ * Components, so the channel token never reaches the browser. The construction
+ * mirrors the dashboard's `SdkClientService` (see
+ * app/dashboard/src/service/sdk-client.service.ts), adapted to read from env.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+
+let client: ForgeCartShopClient | null = null;
+
+/**
+ * Lazily construct and memoize the shop client.
+ *
+ * Constructing per-request would open a fresh websocket transport each time, so
+ * we keep a singleton for the lifetime of the server process.
+ */
+export function getShopClient(): ForgeCartShopClient {
+  if (!SHOP_API_URL) {
+    throw new Error(
+      'FORGECART_SHOP_API_URL is not set. Add it to .env.local (forgecart init writes it for you).',
+    );
+  }
+  if (!CHANNEL_TOKEN) {
+    throw new Error(
+      'FORGECART_CHANNEL_TOKEN is not set. Add it to .env.local (forgecart init writes it for you).',
+    );
+  }
+  if (!client) {
+    client = new ForgeCartShopClient({
+      endpoint: SHOP_API_URL,
+      channelToken: CHANNEL_TOKEN,
+    });
+  }
+  return client;
+}
+
+/** Convenience singleton for direct use in Server Components. */
+export const shopClient = (): ForgeCartShopClient => getShopClient();
+
+/* ------------------------------------------------------------------ *
+ * Typed product helpers
+ *
+ * The generated typed operations (`shopClient.product.shopProducts` /
+ * `.shopProduct`) only select `id` + `optionGroups`, which is not enough to
+ * render a storefront. We therefore use the SDK's supported raw-query escape
+ * hatch (`ForgeCartShopClient.query<T>(document, variables)`) with documents
+ * that select the display fields. Every field below exists on the shop schema's
+ * `Product` / `ProductVariant` / `Asset` / `ProductList` types (available via
+ * `@forgecart/sdk/shop`).
+ * ------------------------------------------------------------------ */
+
+/** A single purchasable variant of a product. Prices are minor units (cents). */
+export interface StorefrontVariant {
+  id: string;
+  name: string;
+  sku: string | null;
+  /** Price in minor currency units (e.g. cents). */
+  price: number;
+  /** Price including tax, in minor currency units. */
+  priceWithTax: number;
+}
+
+/** A product as the storefront renders it. */
+export interface StorefrontProduct {
+  id: string;
+  name: string;
+  slug: string;
+  description: string | null;
+  /** Preview URL of the featured image, if any. */
+  featuredAsset: { id: string; preview: string } | null;
+  variants: StorefrontVariant[];
+}
+
+/** A page of products plus the total count for pagination. */
+export interface StorefrontProductList {
+  items: StorefrontProduct[];
+  totalItems: number;
+}
+
+const PRODUCT_FIELDS = `
+  id
+  name
+  slug
+  description
+  featuredAsset {
+    id
+    preview
+  }
+  variants {
+    id
+    name
+    sku
+    price
+    priceWithTax
+  }
+`;
+
+const PRODUCTS_QUERY = `query StorefrontProducts($options: ListQueryOptions) {
+  products(options: $options) {
+    items {${PRODUCT_FIELDS}}
+    totalItems
+  }
+}`;
+
+const PRODUCT_BY_SLUG_QUERY = `query StorefrontProduct($slug: String) {
+  product(slug: $slug) {${PRODUCT_FIELDS}}
+}`;
+
+const PRODUCT_BY_ID_QUERY = `query StorefrontProductById($id: ID) {
+  product(id: $id) {${PRODUCT_FIELDS}}
+}`;
+
+interface ProductsQueryResult {
+  products: {
+    items: StorefrontProduct[];
+    totalItems: number;
+  };
+}
+
+interface ProductQueryResult {
+  product: StorefrontProduct | null;
+}
+
+/**
+ * Fetch a page of products for the channel.
+ *
+ * `take` / `skip` map onto the shop API's `ListQueryOptions`.
+ */
+export async function getProducts(
+  options: { take?: number; skip?: number } = {},
+): Promise<StorefrontProductList> {
+  const { take = 24, skip = 0 } = options;
+  const result = await getShopClient().query<ProductsQueryResult>(PRODUCTS_QUERY, {
+    options: { take, skip },
+  });
+  return {
+    items: result.products.items,
+    totalItems: result.products.totalItems,
+  };
+}
+
+/** Fetch a single product by its URL slug. Returns `null` if not found. */
+export async function getProductBySlug(slug: string): Promise<StorefrontProduct | null> {
+  const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_SLUG_QUERY, {
+    slug,
+  });
+  return result.product ?? null;
+}
+
+/** Fetch a single product by id. Returns `null` if not found. */
+export async function getProductById(id: string): Promise<StorefrontProduct | null> {
+  const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_ID_QUERY, {
+    id,
+  });
+  return result.product ?? null;
+}
+
+/**
+ * Convenience: fetch a small set of products to feature on the home page.
+ */
+export async function getFeaturedProducts(count = 4): Promise<StorefrontProduct[]> {
+  const { items } = await getProducts({ take: count });
+  return items;
+}
+
+/** Lowest variant price for a product, in minor units, or `null` if none. */
+export function getStartingPrice(product: StorefrontProduct): number | null {
+  if (product.variants.length === 0) {
+    return null;
+  }
+  return product.variants.reduce(
+    (min, v) => (v.priceWithTax < min ? v.priceWithTax : min),
+    product.variants[0].priceWithTax,
+  );
+}
+
+/**
+ * Format a minor-unit price (cents) as a currency string. Defaults to USD;
+ * pass a different ISO currency code as needed.
+ */
+export function formatPrice(minorUnits: number, currency = 'USD'): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(minorUnits / 100);
+}

package/{dist/templates/storefront-additions → templates/storefront}/tailwind.config.js

@@ -5,4 +5,4 @@ module.exports = {
     extend: {},
   },
   plugins: [],
-}
+};

package/templates/storefront/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Vendure
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.