@doswiftly/cli 0.1.1

package/templates/storefront-nextjs/.github/workflows/preview.yml

@@ -0,0 +1,22 @@
+name: Preview Deployment
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: npx doswiftly deploy run --type PREVIEW --branch ${{ github.head_ref }}
+        env:
+          DOSWIFTLY_DEPLOY_TOKEN: ${{ secrets.DOSWIFTLY_DEPLOY_TOKEN }}
+          NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
+          NEXT_PUBLIC_SHOP_SLUG: ${{ secrets.NEXT_PUBLIC_SHOP_SLUG }}

package/templates/storefront-nextjs/README.md

@@ -0,0 +1,520 @@
+# DoSwiftly Storefront Template
+
+A modern, production-ready e-commerce storefront built with Next.js 15 and the DoSwiftly Commerce SDK.
+
+## Features
+
+- ⚡ **Next.js 15** - App Router, Server Components, React 19
+- 🛒 **Commerce SDK** - Type-safe GraphQL API integration
+- 💱 **Multi-currency** - Automatic currency switching with SSR support
+- 🎨 **TailwindCSS** - Beautiful, responsive UI
+- 🔒 **Type-safe** - Full TypeScript support
+- 🚀 **Hybrid Architecture** - RSC for SEO, Client for interactivity
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+```
+
+---
+
+## Architecture: RSC vs Client Components
+
+This template uses a **hybrid architecture** that combines React Server Components (RSC) for performance and SEO with Client Components for interactivity.
+
+### When to Use RSC (Server)
+
+| Use Case            | Reason                  |
+| ------------------- | ----------------------- |
+| Product listings    | SEO, cacheability       |
+| Category pages      | SEO, static content     |
+| Collection pages    | SEO, static content     |
+| Search results      | SEO for search engines  |
+| Single product info | SEO, initial load speed |
+
+### When to Use Client Components
+
+| Use Case           | Reason                         |
+| ------------------ | ------------------------------ |
+| Shopping cart      | Real-time updates, mutations   |
+| Add to cart button | User interaction               |
+| Account/profile    | User-specific, mutations       |
+| Checkout           | Forms, payments, interactivity |
+| Currency selector  | Client-side state              |
+
+### Route Architecture
+
+```
+/app
+├── layout.tsx (RSC)
+│   └── providers.tsx (Client) ← QueryClient + StorefrontProvider
+│
+├── page.tsx (RSC) ← useProducts, useCategories
+├── products/
+│   ├── page.tsx (RSC) ← useProducts
+│   └── [slug]/page.tsx (RSC + Client island)
+│       └── <ProductActions/> (Client) ← Add to cart
+│
+├── categories/
+│   ├── page.tsx (RSC) ← useCategories
+│   └── [slug]/page.tsx (RSC) ← useCategory, useProducts
+│
+├── collections/
+│   ├── page.tsx (RSC) ← useCollections
+│   └── [slug]/page.tsx (RSC) ← useCollection, useProducts
+│
+├── search/page.tsx (RSC) ← useProducts
+│
+├── cart/page.tsx (Client) ← useCart, useCartLinesUpdate
+│
+├── account/
+│   ├── page.tsx (Client) ← useCustomer
+│   └── login/page.tsx (Client) ← useCustomerLogin
+│
+└── checkout/page.tsx (Client) ← Full interactivity
+```
+
+---
+
+## Data Fetching
+
+> **🔑 IMPORTANT:** Both server and client return **normalized data** (flat arrays).  
+> GraphQL edges/nodes are automatically unwrapped. No `.edges.map((e) => e.node)` needed!
+>
+> This provides the best developer experience and seamless migration between RSC and Client components.
+
+### Server Components (RSC)
+
+Import from `@doswiftly/commerce-sdk/graphql/server`:
+
+```typescript
+import {
+  useProducts,
+  useProduct,
+  useCategories,
+} from "@doswiftly/commerce-sdk/graphql/server";
+
+// All functions return normalized data (no edges/nodes)
+// Cached per-request via React cache()
+export default async function ProductsPage() {
+  const { products, pageInfo } = await useProducts({ first: 10 });
+  const { categories } = await useCategories();
+
+  // products is already a flat array - no .edges.map needed!
+  return <ProductGrid products={products} />;
+}
+```
+
+**Available server helpers:**
+
+- `useProducts()` - Product listings with pagination
+- `useProduct()` - Single product by handle
+- `useCategories()` - All categories
+- `useCategory()` - Single category by slug
+- `useCollections()` - All collections
+- `useCollection()` - Single collection by handle
+- `useCart()` - Cart by ID
+- `useShop()` - Shop configuration
+- `useCustomer()` - Authenticated customer data
+
+### Client Components
+
+Import from `@doswiftly/commerce-sdk/graphql/client`:
+
+```tsx
+"use client";
+
+import {
+  useProducts,
+  useCart,
+  useCartLinesAdd,
+} from "@doswiftly/commerce-sdk/graphql/client";
+
+export function ProductList() {
+  // React Query hook - returns normalized data (same as server!)
+  const { data, isLoading } = useProducts({ first: 10 });
+
+  if (isLoading) return <Skeleton />;
+
+  // data.products is already a flat array!
+  return <Grid products={data?.products} />;
+}
+
+export function AddToCartButton({ variantId }: { variantId: string }) {
+  const { mutate: addToCart, isPending } = useCartLinesAdd();
+
+  return (
+    <button
+      onClick={() =>
+        addToCart({
+          cartId,
+          lines: [{ merchandiseId: variantId, quantity: 1 }],
+        })
+      }
+      disabled={isPending}
+    >
+      {isPending ? "Adding..." : "Add to Cart"}
+    </button>
+  );
+}
+```
+
+**Available client hooks:**
+
+Queries:
+
+- `useProducts()` - Product listings
+- `useProduct()` - Single product
+- `useCategories()` - Categories
+- `useCategory()` - Single category
+- `useCollections()` - Collections
+- `useCollection()` - Single collection
+- `useCart()` - Cart data
+- `useCustomer()` - Customer data
+
+Mutations:
+
+- `useCartCreate()` - Create new cart
+- `useCartLinesAdd()` - Add items to cart
+- `useCartLinesUpdate()` - Update cart items
+- `useCartLinesRemove()` - Remove from cart
+- `useCustomerLogin()` - Login
+- `useCustomerCreate()` - Register
+- `useCustomerLogout()` - Logout
+
+---
+
+## Naming Convention
+
+Both server and client use **identical function names AND return structures**:
+
+```typescript
+// Server (RSC) - async function, returns normalized data
+import { useProducts } from "@doswiftly/commerce-sdk/graphql/server";
+const { products, pageInfo } = await useProducts({ first: 10 });
+// products is a flat array ✅
+
+// Client - React Query hook, returns normalized data (same!)
+import { useProducts } from "@doswiftly/commerce-sdk/graphql/client";
+const { data } = useProducts({ first: 10 });
+const products = data?.products; // Also a flat array ✅
+```
+
+### Return Types Comparison
+
+| Aspect      | Server (`/server`)                    | Client (`/client`)                           |
+| ----------- | ------------------------------------- | -------------------------------------------- |
+| Return type | `Promise<NormalizedProductsResponse>` | `UseQueryResult<NormalizedProductsResponse>` |
+| Data access | `const { products, pageInfo }`        | `const { data }` → `data.products`           |
+| Data format | **Flat array** (normalized, no edges) | **Flat array** (normalized, no edges)        |
+| Loading     | N/A (await)                           | `isLoading`, `isFetching`                    |
+| Error       | try/catch                             | `error`, `isError`                           |
+| Refetch     | Call again                            | `refetch()`                                  |
+| Cache       | `React.cache()` per-request           | React Query client cache                     |
+
+---
+
+## Authentication & Session Persistence
+
+### How It Works
+
+1. **Login** → `useCustomerLogin()` mutation returns token
+2. **Token stored** in cookie: `doswiftly_customer_token`
+3. **Page refresh**:
+   - RSC reads cookie → injects `X-Customer-Token` header
+   - Client hydrates with same state from server props
+4. **No flash of unauthenticated content**
+
+### Implementation
+
+```tsx
+// RSC - automatically authenticated via cookies
+import { useCustomer } from "@doswiftly/commerce-sdk/graphql/server";
+
+export default async function AccountPage() {
+  const { customer } = await useCustomer();
+
+  if (!customer) {
+    redirect("/login");
+  }
+
+  return <Profile customer={customer} />;
+}
+
+// Client - same pattern with loading state
+("use client");
+import { useCustomer, useAuth } from "@doswiftly/commerce-sdk/graphql/client";
+
+export function ProfileClient() {
+  const { data, isLoading } = useCustomer();
+  const { logout } = useAuth();
+
+  if (isLoading) return <Skeleton />;
+  if (!data?.customer) return <LoginPrompt />;
+
+  return <Profile customer={data.customer} onLogout={logout} />;
+}
+```
+
+---
+
+## Currency Handling
+
+### Automatic Currency Injection
+
+Currency is read from `doswiftly_preferred_currency` cookie and automatically applied to all GraphQL requests.
+
+### Changing Currency
+
+```tsx
+"use client";
+import { useCurrency } from "@doswiftly/commerce-sdk/graphql/react";
+import { useRouter } from "next/navigation";
+
+export function CurrencySelector() {
+  const { currency, setCurrency, availableCurrencies } = useCurrency();
+  const router = useRouter();
+
+  const handleChange = (newCurrency: string) => {
+    setCurrency(newCurrency); // Updates cookie + context
+    router.refresh(); // Refreshes RSC pages with new currency
+  };
+
+  return (
+    <select value={currency} onChange={(e) => handleChange(e.target.value)}>
+      {availableCurrencies.map((c) => (
+        <option key={c} value={c}>
+          {c}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+## Filtering & Sorting
+
+### Filter Products
+
+```typescript
+const { products } = await useProducts({
+  first: 20,
+  filters: {
+    minPrice: 50,
+    maxPrice: 200,
+    vendor: "Nike",
+    available: true,
+  },
+  sortKey: "PRICE",
+  reverse: false, // ascending
+});
+```
+
+### Available Filters
+
+| Filter        | Type    | Description        |
+| ------------- | ------- | ------------------ |
+| `minPrice`    | number  | Minimum price      |
+| `maxPrice`    | number  | Maximum price      |
+| `vendor`      | string  | Brand/vendor name  |
+| `available`   | boolean | Stock availability |
+| `productType` | string  | Product type       |
+| `tag`         | string  | Product tag        |
+
+### Sort Keys
+
+- `TITLE` - Alphabetically
+- `PRICE` - By price
+- `CREATED_AT` - By date
+- `BEST_SELLING` - By popularity
+
+---
+
+## Pagination
+
+Cursor-based pagination for all list endpoints:
+
+```typescript
+const { products, pageInfo } = await useProducts({ first: 10 });
+
+if (pageInfo?.hasNextPage) {
+  const nextPage = await useProducts({
+    first: 10,
+    after: pageInfo.endCursor,
+  });
+}
+```
+
+---
+
+## Island of Interactivity Pattern
+
+Combine RSC and Client Components for optimal performance:
+
+```tsx
+// app/products/[slug]/page.tsx (RSC)
+import { useProduct } from "@doswiftly/commerce-sdk/graphql/server";
+import { AddToCartButton } from "@/components/commerce/add-to-cart";
+
+export default async function ProductPage({ params }) {
+  const { product } = await useProduct({ handle: params.slug });
+
+  return (
+    <div>
+      {/* RSC - Static, SEO-friendly */}
+      <h1>{product.title}</h1>
+      <p>{product.description}</p>
+      <img src={product.featuredImage?.url} alt={product.title} />
+
+      {/* Client Island - Interactive */}
+      <AddToCartButton productId={product.id} variants={product.variants} />
+    </div>
+  );
+}
+```
+
+```tsx
+// components/commerce/add-to-cart.tsx (Client)
+"use client";
+
+import { useCartManager } from "@doswiftly/commerce-sdk/graphql/react";
+
+export function AddToCartButton({ productId, variants }) {
+  const { addItem, loading } = useCartManager();
+  const [quantity, setQuantity] = useState(1);
+  const [selectedVariant, setSelectedVariant] = useState(variants[0]?.id);
+
+  return (
+    <div>
+      <QuantitySelector value={quantity} onChange={setQuantity} />
+      <VariantSelector
+        variants={variants}
+        value={selectedVariant}
+        onChange={setSelectedVariant}
+      />
+      <button
+        onClick={() => addItem(selectedVariant, quantity)}
+        disabled={loading}
+      >
+        {loading ? "Adding..." : "Add to Cart"}
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## Environment Variables
+
+```env
+# Required
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_SHOP_SLUG=your-shop-slug
+
+# Optional
+NEXT_PUBLIC_SITE_NAME=My Store
+```
+
+---
+
+## Project Structure
+
+```
+app/
+  layout.tsx              # Root layout (RSC)
+  page.tsx                # Homepage (RSC)
+  products/
+    page.tsx              # Product listing (RSC)
+    [slug]/page.tsx       # Product detail (RSC + Client)
+  categories/
+    page.tsx              # Categories (RSC)
+    [slug]/page.tsx       # Category products (RSC)
+  collections/
+    page.tsx              # Collections (RSC)
+    [slug]/page.tsx       # Collection products (RSC)
+  search/page.tsx         # Search results (RSC)
+  cart/page.tsx           # Shopping cart (Client)
+  account/
+    page.tsx              # Account dashboard (Client)
+    login/page.tsx        # Login form (Client)
+
+components/
+  commerce/
+    add-to-cart.tsx       # Add to cart button (Client)
+    currency-selector.tsx # Currency switcher (Client)
+    product-actions.tsx   # Product page actions (Client)
+  providers.tsx           # QueryClient + StorefrontProvider (Client)
+```
+
+---
+
+## Migration from Raw GraphQL
+
+If you're migrating from a previous version that returned raw GraphQL responses (edges/nodes), here's what changed:
+
+### ✅ Before (Raw GraphQL)
+
+```tsx
+// Client hooks returned raw edges/nodes
+const { data } = useProducts({ first: 10 });
+const products = data?.products.edges.map((e) => e.node);
+```
+
+### ✅ After (Normalized)
+
+```tsx
+// Client hooks now return flat arrays (same as server)
+const { data } = useProducts({ first: 10 });
+const products = data?.products; // Already flat!
+```
+
+### Migration Steps
+
+1. **Remove `.edges.map((e) => e.node)`** from all client components
+2. **Access data directly**: `data.products` instead of `data.products.edges`
+3. **PageInfo unchanged**: Still accessed via `data.pageInfo`
+
+### Why This Change?
+
+- **Consistency**: Server and client APIs are now identical
+- **Developer Experience**: Zero boilerplate, less code
+- **Fewer Errors**: No more "Cannot read properties of undefined (reading 'map')"
+- **Seamless Migration**: Move components between RSC/Client without changes
+
+### Need Raw GraphQL?
+
+For advanced use cases requiring raw GraphQL (custom fragments, \_\_typename, etc.), use `graphql-request` directly:
+
+```typescript
+import { GraphQLClient } from "graphql-request";
+import { gql } from "graphql-tag";
+
+const client = new GraphQLClient(apiUrl);
+const data = await client.request(gql`
+  query {
+    products(first: 10) {
+      edges {
+        node {
+          id
+          __typename
+        }
+        cursor
+      }
+    }
+  }
+`);
+```
+
+---
+
+## License
+
+MIT