@doswiftly/cli 0.1.18 → 0.1.19

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

@@ -0,0 +1,47 @@
+name: Preview Deployment
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    env:
+      NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
+      NEXT_PUBLIC_SHOP_SLUG: ${{ secrets.NEXT_PUBLIC_SHOP_SLUG }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Detect package manager
+        id: pm
+        run: |
+          if [ -f pnpm-lock.yaml ]; then
+            echo "manager=pnpm" >> $GITHUB_OUTPUT
+            echo "install=pnpm install --frozen-lockfile" >> $GITHUB_OUTPUT
+          elif [ -f yarn.lock ]; then
+            echo "manager=yarn" >> $GITHUB_OUTPUT
+            echo "install=yarn install --frozen-lockfile" >> $GITHUB_OUTPUT
+          else
+            echo "manager=npm" >> $GITHUB_OUTPUT
+            echo "install=npm ci" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup pnpm
+        if: steps.pm.outputs.manager == 'pnpm'
+        uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: ${{ steps.pm.outputs.manager }}
+
+      - name: Install dependencies
+        run: ${{ steps.pm.outputs.install }}
+
+      - name: Deploy preview
+        run: |
+          npx --yes @doswiftly/cli@latest --version
+          npx @doswiftly/cli@latest deploy run --type PREVIEW --branch ${{ github.head_ref }}
+        env:
+          DOSWIFTLY_DEPLOY_TOKEN: ${{ secrets.DOSWIFTLY_DEPLOY_TOKEN }}

package/templates/storefront-nextjs-shadcn/CLAUDE.md

@@ -6,39 +6,87 @@ Ten plik jest synchronizowany do `storefronts/test-shop/` przez `pnpm sync:store
 
 ```
 app/                    # Next.js 15 App Router
-├── layout.tsx          # Root layout z providers
+├── layout.tsx          # Root layout z StorefrontProvider + QueryProvider
 ├── page.tsx            # Homepage
-├── products/           # Strony produktow
+├── products/           # Strony produktow (SSR + client hydration)
 ├── collections/        # Strony kolekcji
-├── cart/               # Koszyk
-├── checkout/           # Checkout
-├── account/            # Panel klienta
-└── auth/               # Login/Register
+├── categories/         # Strony kategorii (SSR metadata + client products)
+├── cart/               # Koszyk (client-only, Zustand + React Query)
+├── checkout/           # Checkout (client-only, multi-step mutations)
+├── account/            # Panel klienta (auth required)
+├── auth/               # Login/Register
+└── blog/               # Blog (SSR)
 
 components/
 ├── product/            # ProductCard, ProductGrid, AddToCartButton
+│   ├── product-card.fragment.graphql   # Colocated fragment
+│   ├── product-detail.fragment.graphql
+│   └── product-variant.fragment.graphql
 ├── cart/               # CartDrawer, CartItem, CartSummary
-├── auth/               # LoginForm, RegisterForm
+│   └── cart-line.fragment.graphql
+├── home/               # FeaturedCollections, Hero
+│   └── collection-card.fragment.graphql
+├── account/            # OrderCard, CustomerInfo
+│   ├── order-summary.fragment.graphql
+│   └── customer-info.fragment.graphql
 ├── layout/             # Header, Footer, Navigation
+│   └── category-node.fragment.graphql
+├── auth/               # LoginForm, RegisterForm
 ├── ui/                 # shadcn/ui components
-└── providers/          # QueryProvider, CurrencyProvider, ThemeProvider
+└── providers/          # QueryProvider, ThemeProvider
 
 lib/
 ├── graphql/
-│   ├── server.ts       # SSR helpers z React cache()
-│   ├── client.ts       # Client-side GraphQL client
-│   └── hooks.ts        # React Query hooks
-└── currency/           # Currency management
-
-stores/                 # Zustand stores
-├── cart-store.ts       # Koszyk (persist localStorage)
-├── currency-store.ts   # Waluta (persist cookies)
-└── auth-store.ts       # Autentykacja
+│   ├── config.ts       # Centralized API config (SSOT for apiUrl, shopSlug)
+│   ├── query-keys.ts   # Centralized React Query keys
+│   ├── client.ts       # useExecute() hook — uses SDK StorefrontClient from Context
+│   ├── server.ts       # SSR helpers z React.cache()
+│   ├── hooks.ts        # React Query hooks (useProducts, useCart, etc.)
+│   ├── types.ts        # Domain types derived from codegen (query result shapes)
+│   └── fragments.ts    # Fragment type re-exports (component data contracts)
+├── auth/
+│   └── routes.ts       # Route lists + re-exports AUTH_COOKIE_NAME/matchesRoute from SDK
+└── theme/
+    └── theme-config.ts # Theme tokens (colors, storage key)
+
+graphql/
+└── custom.example.graphql  # Example custom operations
+
+stores/                 # Zustand stores (Context pattern via SDK createStoreContext)
+├── cart-store.ts       # Cart UI state (cartId, isOpen) — items from server
+├── checkout-store.ts   # Checkout form state with persistence
+└── wishlist-store.ts   # Wishlist state with persistence
+
+hooks/
+├── use-auth.ts         # Thin wrapper over SDK useAuth + httpOnly cookies
+├── use-auth-sync.ts    # Detects auth desync (cookie vs store)
+├── use-cart-actions.ts # Cart mutations with debounce + race condition protection
+├── use-cart-sync.ts    # Cart data from server (maps GraphQL → CartItemData)
+└── use-filter-params.ts # URL-driven filter state
 
 generated/
-└── graphql.ts          # Auto-generowane typy
+└── graphql.ts          # Auto-generated types + TypedDocumentString constants
 ```
 
+## SDK Integration
+
+Template importuje z `@doswiftly/storefront-sdk`:
+- **Core (`.`)**: `AUTH_COOKIE_NAME`, `matchesRoute`, `createSetTokenHandler`, `createClearTokenHandler`, `createAuthTokenClient`, `formatPrice`, `formatAmount`, `sanitizeHtml`, `normalizeConnection`
+- **React (`./react`)**: `StorefrontProvider`, `useAuthStore`, `useCurrencyStore`, `useAuthHydrated`, `useStorefrontClient`, `useHydrated`, `useDebouncedValue`, `createStoreContext`
+- **Server (`./react/server`)**: `getStorefrontClient`, `getCurrencyFromCookieAsync`
+- **Auth hooks**: `useAuth` (bazowy, owinięty w `hooks/use-auth.ts`)
+
+**Store pattern**: Zustand stores używają `createStore()` (vanilla) + React Context via `createStoreContext()` from SDK.
+Hooki `useAuthStore`/`useCurrencyStore` wymagają owinięcia w `StorefrontProvider`.
+Template stores (cart, checkout, wishlist) wymagają `StoresProvider` (wewnątrz `StorefrontProvider`).
+`useAuthHydrated()` zwraca `true` po rehydracji persist z localStorage.
+`useHydrated()` zwraca `true` po hydration SSR → client.
+
+Template NIE importuje z SDK:
+- React Query hooks — są LOCAL w `lib/graphql/hooks.ts`
+- Cart actions — LOCAL w `hooks/use-cart-actions.ts`
+- Data types — LOCAL via codegen (`generated/graphql.ts`)
+
 ## Data Fetching
 
 ### Server Components (lib/graphql/server.ts):
@@ -59,38 +107,103 @@ const { data, isLoading } = useProducts({ first: 20 });
 const addLines = useCartLinesAdd();
 ```
 
-## Zustand Stores
+### SSR → Client Hydration Pattern:
+```typescript
+// Server Component (page.tsx)
+const { product } = await fetchProduct(slug);
+return <ProductClient product={product} />;
+
+// Client Component (product-client.tsx)
+const { data } = useProduct(handle, {
+  placeholderData: currencyMatches ? { product: initialProduct } : undefined,
+});
+// placeholderData shows SSR data while React Query refetches with correct currency
+```
+
+## Fragment-First Architecture (Colocated Fragments)
+
+Fragments are **colocated** next to their components (Hydrogen/Relay pattern):
+
+```
+components/product/product-card.fragment.graphql  → ProductCardFieldsFragment
+components/cart/cart-line.fragment.graphql         → CartLineFieldsFragment
+```
+
+Import fragment types via the stable API layer, not directly from codegen:
 
-### Cart Store:
 ```typescript
-import { useCartStore } from '@/stores/cart-store';
+// Component uses fragment type for props:
+import type { ProductCardFields } from '@/lib/graphql/fragments';
 
-const { items, addItem, removeItem, getTotalItems, getTotalPrice } = useCartStore();
+interface ProductCardProps {
+  product: ProductCardFields;
+}
 ```
 
-### Currency Store:
+**Convention**: When a GraphQL fragment exists for data your component receives, use the fragment type — do NOT define a local interface.
+
+Codegen picks up colocated fragments via `components/**/*.fragment.graphql` glob.
+Run `pnpm codegen` after adding new `.fragment.graphql` files.
+
+## Why fragmentMasking is disabled
+
+`codegen.ts` sets `fragmentMasking: false`. This means:
+- Fragment types are plain TS types (structural typing, no `$fragmentName` branding)
+- Components can accept both fragment types and supertypes from query results
+- Does NOT require `useFragment()` helpers (Relay pattern)
+
+Trade-off: a component could technically access fields outside its fragment.
+We accept this intentionally — simplicity and DX > strict data masking.
+If the project scales to multiple teams, consider `fragmentMasking: true`.
+
+## Query Keys
+
+All React Query keys are centralized in `lib/graphql/query-keys.ts`:
+
 ```typescript
-import { useCurrencyStore } from '@/stores/currency-store';
+import { queryKeys } from '@/lib/graphql/query-keys';
+
+// Reading data:
+useQuery({ queryKey: queryKeys.products.detail(slug, currency), ... });
 
-const { currency, setCurrency, supportedCurrencies } = useCurrencyStore();
+// Invalidating:
+queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
 ```
 
+## Cart Race Condition Protection
+
+Cart mutations use three layers of protection:
+1. **cancelQueries** — Cancel in-flight cart queries before mutation
+2. **Debounce** — 500ms debounce on quantity updates
+3. **onSettled invalidation** — Refetch cart after mutation success OR error
+
 ## Konwencje
 
 1. **Client vs Server**: Dodaj `"use client"` tylko gdy potrzebne (hooks, interaktywnosc)
-2. **Typy**: Zawsze definiuj interfejsy dla props
-3. **Styling**: Uzywaj `cn()` dla laczenia klas Tailwind
-4. **Obrazki**: next/image z alt i priority dla LCP
-5. **Formularze**: Zod dla walidacji
+2. **Fragment types**: Import z `@/lib/graphql/fragments`, NIE z `@/generated/graphql`
+3. **No local interfaces**: Gdy istnieje fragment type, uzywaj go zamiast local interface
+4. **Colocated fragments**: `.fragment.graphql` obok komponentu w `components/`
+5. **Styling**: Uzywaj `cn()` dla laczenia klas Tailwind
+6. **Obrazki**: next/image z alt i priority dla LCP
+7. **Formularze**: Zod + react-hook-form
+8. **Query keys**: Zawsze z `queryKeys.*` (nie hardcoded arrays)
+9. **Config**: Zawsze z `graphqlConfig` (nie duplikuj env var resolution)
 
 ## GraphQL Operations
 
-Operacje sa zdefiniowane w:
+Operacje i schemat sa zdefiniowane w:
+```
+packages/@doswiftly/storefront-operations/
+├── schema.graphql       # Schemat GraphQL (zsynchronizowany z backendu)
+├── queries.graphql      # Zapytania
+├── mutations.graphql    # Mutacje
+└── fragments.graphql    # Fragmenty (backend SSOT)
+```
+
+Colocated component fragments:
 ```
-packages/backend/src/commerce/storefront-graphql/operations/
-├── queries.graphql
-├── mutations.graphql
-└── fragments.graphql
+components/**/*.fragment.graphql   # UI component fragments (Hydrogen/Relay pattern)
 ```
 
-Aby poznac dostepne operacje, przeczytaj te pliki.
+Codegen NIE wymaga uruchomionego backendu — schemat pochodzi z pliku.
+Aby poznac dostepne operacje, przeczytaj pliki `.graphql` w storefront-operations.

package/templates/storefront-nextjs-shadcn/README.md

@@ -1,194 +1,61 @@
-# DoSwiftly Storefront - shadcn/ui Template
+# DoSwiftly Storefront — shadcn/ui Template
 
-This is a Next.js 15+ storefront template with shadcn/ui components, optimized for DoSwiftly Commerce.
+Next.js 15+ storefront template with shadcn/ui, optimized for DoSwiftly Commerce.
 
-## Features
+## Tech Stack
 
-- ✅ **Next.js 15+** with App Router
-- ✅ **shadcn/ui** components pre-configured
-- ✅ **Tailwind CSS v4** for styling
-- ✅ **TypeScript** for type safety
-- ✅ **GraphQL Codegen** for type-safe API calls
-- ✅ **React Query** for data fetching
-- ✅ **Zustand** for state management
-- ✅ **Currency conversion** with client-side switching
+- **Next.js 15+** with App Router and React Server Components
+- **shadcn/ui** + Tailwind CSS v4
+- **@doswiftly/storefront-sdk** — type-safe GraphQL hooks and Zustand stores
+- **GraphQL Codegen** — auto-generated types from backend schema
 
 ## Getting Started
 
-### 1. Install Dependencies
-
 ```bash
 pnpm install
+pnpm run codegen     # Generate GraphQL types
+pnpm run dev         # http://localhost:3000
 ```
 
-### 2. Configure Environment
+### Environment
 
-Copy `.env.example` to `.env.local` and update:
+Copy `.env.example` to `.env.local`:
 
 ```env
 NEXT_PUBLIC_SHOP_SLUG=your-shop-slug
 NEXT_PUBLIC_API_URL=https://api.doswiftly.pl
 ```
 
-### 3. Run GraphQL Codegen
-
-Generate TypeScript types from your GraphQL schema:
+## Project Structure
 
-```bash
-pnpm run codegen
 ```
-
-### 4. Start Development Server
-
-```bash
-pnpm run dev
+app/                    # Next.js App Router pages
+components/
+  ui/                   # shadcn/ui components
+  product/              # Product-related components
+  cart/                 # Cart components
+  layout/               # Header, Footer, Navigation
+  providers/            # QueryProvider, CurrencyProvider
+lib/
+  graphql/              # Server/client GraphQL helpers
+stores/                 # Zustand stores (cart, currency, auth)
+generated/              # Auto-generated GraphQL types
 ```
 
-Open [http://localhost:3000](http://localhost:3000) in your browser.
-
 ## Adding shadcn/ui Components
 
-This template is pre-configured with shadcn/ui. Add components using the shadcn CLI:
-
 ```bash
-# Add a button component
 npx shadcn@latest add button
-
-# Add a dialog component
 npx shadcn@latest add dialog
-
-# Add a dropdown menu
-npx shadcn@latest add dropdown-menu
-
-# See all available components
-npx shadcn@latest add
-```
-
-Components will be added to `components/ui/` directory.
-
-## Project Structure
-
-```
-├── app/                    # Next.js App Router pages
-│   ├── layout.tsx         # Root layout with providers
-│   └── page.tsx           # Homepage
-├── components/
-│   ├── ui/                # shadcn/ui components (auto-generated)
-│   ├── layout/            # Layout components (Header, Footer)
-│   └── providers/         # React providers (Query, Currency)
-├── lib/
-│   ├── graphql/
-│   │   ├── server.ts      # Server-side GraphQL client
-│   │   ├── client.ts      # Client-side GraphQL client
-│   │   └── hooks.ts       # React Query hooks
-│   └── utils.ts           # Utility functions (cn helper)
-├── stores/
-│   └── currency-store.ts  # Zustand currency store
-├── generated/
-│   └── graphql.ts         # Auto-generated GraphQL types
-├── doswiftly.config.ts    # DoSwiftly configuration
-├── components.json        # shadcn/ui configuration
-└── codegen.ts             # GraphQL Codegen configuration
-```
-
-## GraphQL Codegen
-
-This template uses GraphQL Codegen to generate TypeScript types from your GraphQL schema.
-
-### Configuration
-
-See `codegen.ts` for configuration. It reads:
-- **Schema**: From your DoSwiftly API
-- **Operations**: From `@doswiftly/storefront-operations` package
-- **Custom queries**: From `src/graphql/**/*.{ts,tsx}`
-
-### Running Codegen
-
-```bash
-# Generate types
-pnpm run codegen
-
-# Watch mode (auto-regenerate on changes)
-pnpm run codegen:watch
-```
-
-## Currency Management
-
-This template includes built-in currency conversion:
-
-1. **Server Components**: Render prices in base currency (SSG-compatible)
-2. **Client Components**: Switch to user's preferred currency dynamically
-3. **Currency Store**: Persists user preference in localStorage
-
-### Usage
-
-```tsx
-// Server Component
-import { fetchProduct } from '@/lib/graphql/server';
-
-export default async function ProductPage({ params }) {
-  const { product } = await fetchProduct(params.handle);
-  // Prices in base currency
-  return <div>{product.priceRange.minVariantPrice.amount}</div>;
-}
-
-// Client Component
-'use client';
-import { useProduct } from '@/lib/graphql/hooks';
-import { useCurrencyStore } from '@/stores/currency-store';
-
-export function ProductPrice({ handle }) {
-  const currency = useCurrencyStore((s) => s.currency);
-  const { data } = useProduct(handle);
-  // Prices in user's preferred currency
-  return <div>{data.product.priceRange.minVariantPrice.amount} {currency}</div>;
-}
-```
-
-## Styling
-
-This template uses Tailwind CSS v4 with shadcn/ui.
-
-### Customizing Theme
-
-Edit `app/globals.css` to customize colors:
-
-```css
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
-    /* ... more variables */
-  }
-}
-```
-
-### Using cn() Helper
-
-The `cn()` helper combines Tailwind classes with proper precedence:
-
-```tsx
-import { cn } from '@/lib/utils';
-
-<div className={cn('text-base', isActive && 'text-primary')} />
-```
-
-## Building for Production
-
-```bash
-# Build
-pnpm run build
-
-# Start production server
-pnpm run start
 ```
 
-## Learn More
+## Documentation
 
-- [DoSwiftly Documentation](https://docs.doswiftly.pl)
-- [shadcn/ui Documentation](https://ui.shadcn.com)
-- [Next.js Documentation](https://nextjs.org/docs)
-- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [SDK Overview](https://docs.doswiftly.pl/storefront-developer/sdk/overview) — hooks, stores, architecture
+- [SDK Products](https://docs.doswiftly.pl/storefront-developer/sdk/products) — product queries and mutations
+- [API Queries](https://docs.doswiftly.pl/storefront-developer/api/queries) — available GraphQL queries
+- [API Mutations](https://docs.doswiftly.pl/storefront-developer/api/mutations) — available GraphQL mutations
+- [CLI Commands](https://docs.doswiftly.pl/storefront-developer/cli-commands) — full CLI reference
 
 ## License