@doswiftly/cli 0.1.1

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

@@ -0,0 +1,307 @@
+# Product Detail Page Implementation
+
+## Overview
+
+This document describes the implementation of the product detail page (Task 21) following the Next.js 15+ App Router architecture with Server Components and Client Components.
+
+## Implementation Summary
+
+### Files Created/Modified
+
+1. **`app/products/[slug]/page.tsx`** - Server Component (MODIFIED)
+   - Converted from Client Component to Server Component
+   - Added metadata generation for SEO
+   - Added structured data (JSON-LD) for search engines
+   - Added static params generation for top 100 products
+   - Implemented ISR with 60-second revalidation
+
+2. **`app/products/[slug]/product-client.tsx`** - Client Component (MODIFIED)
+   - Enhanced to handle SSR hydration with currency switching
+   - Added logic to refetch product data when user's preferred currency differs from SSR currency
+   - Added `suppressHydrationWarning` to prevent hydration mismatches
+   - Maintains selected variant across currency changes
+
+3. **`app/not-found.tsx`** - 404 Page (CREATED)
+   - Created custom 404 page for better error handling
+   - Provides helpful navigation back to the site
+
+## Architecture
+
+### Server Component Flow
+
+```
+1. Build Time (SSG)
+   ├─ generateStaticParams() fetches top 100 products
+   ├─ Pre-renders pages for each product handle
+   └─ Uses base currency (no X-Preferred-Currency header)
+
+2. Request Time
+   ├─ Server Component fetches product data (base currency)
+   ├─ Generates metadata (title, description, Open Graph)
+   ├─ Generates JSON-LD structured data
+   └─ Passes initial data to Client Component
+
+3. ISR Revalidation
+   └─ Pages revalidate every 60 seconds
+```
+
+### Client Component Flow
+
+```
+1. Initial Render
+   ├─ Receives product data from Server Component (base currency)
+   ├─ Displays product with SSR data
+   └─ suppressHydrationWarning prevents mismatch
+
+2. Currency Store Initialization
+   ├─ CurrencyProvider initializes from Shop data
+   ├─ Checks localStorage for saved currency
+   ├─ Detects browser locale
+   └─ Sets preferred currency
+
+3. Currency-Aware Refetch
+   ├─ Compares preferred currency vs SSR currency
+   ├─ If different, refetches product with new currency
+   ├─ Updates prices dynamically
+   └─ Maintains selected variant
+```
+
+## Key Features
+
+### 1. Metadata Generation (Requirement 13.1, 13.3)
+
+```typescript
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const data = await fetchProduct(params.slug);
+  const product = data?.product;
+  
+  return {
+    title: product.title,
+    description: product.description,
+    openGraph: {
+      title: product.title,
+      description: product.description,
+      images: [product.images[0]],
+    },
+    twitter: {
+      card: "summary_large_image",
+      // ...
+    },
+  };
+}
+```
+
+**Benefits:**
+- Improved SEO with proper meta tags
+- Better social media sharing with Open Graph
+- Twitter Card support for rich previews
+
+### 2. Structured Data (JSON-LD) (Requirement 13.3)
+
+```typescript
+const jsonLd = {
+  "@context": "https://schema.org",
+  "@type": "Product",
+  name: product.title,
+  description: product.description,
+  image: product.images[0].url,
+  brand: { "@type": "Brand", name: product.vendor },
+  offers: {
+    "@type": "Offer",
+    price: product.priceRange.minVariantPrice.amount,
+    priceCurrency: product.priceRange.minVariantPrice.currencyCode,
+    availability: "https://schema.org/InStock",
+  },
+};
+```
+
+**Benefits:**
+- Rich snippets in search results
+- Better product visibility in Google Shopping
+- Improved search engine understanding
+
+### 3. Static Params Generation (Requirement 2.2, 6.4)
+
+```typescript
+export async function generateStaticParams() {
+  const { products } = await fetchProducts({
+    first: 100,
+    sortKey: "BEST_SELLING",
+  });
+  
+  return products.map((product) => ({
+    slug: product.handle,
+  }));
+}
+```
+
+**Benefits:**
+- Pre-renders top 100 products at build time
+- Instant page loads for popular products
+- Reduced server load
+- Better Core Web Vitals scores
+
+### 4. SSR with Client Hydration (Requirement 2.2, 3.2, 6.4)
+
+**Server Component:**
+```typescript
+export default async function ProductPage({ params }) {
+  const data = await fetchProduct(params.slug);
+  return <ProductClient product={data.product} />;
+}
+```
+
+**Client Component:**
+```typescript
+export function ProductClient({ product: initialProduct }) {
+  const currency = useCurrencyStore((s) => s.currency);
+  const needsRefetch = currency !== initialProduct.priceRange.minVariantPrice.currencyCode;
+  
+  const { data } = useProduct(initialProduct.handle, {
+    initialData: { product: initialProduct },
+    enabled: needsRefetch,
+  });
+  
+  const product = data?.product || initialProduct;
+  
+  return (
+    <div suppressHydrationWarning>
+      <ProductPrice price={product.priceRange.minVariantPrice} />
+    </div>
+  );
+}
+```
+
+**Benefits:**
+- Fast initial render with SSR
+- Dynamic currency switching without page reload
+- No hydration mismatches
+- Optimal user experience
+
+### 5. ISR Configuration
+
+```typescript
+export const revalidate = 60;
+```
+
+**Benefits:**
+- Pages stay fresh with 60-second revalidation
+- Maintains static generation benefits
+- Automatic updates when products change
+- No manual cache invalidation needed
+
+## Requirements Validation
+
+✅ **Requirement 2.2**: Server Component renders prices in base currency for SSG  
+✅ **Requirement 3.2**: Client Component renders prices in preferred currency  
+✅ **Requirement 6.4**: Clear separation between server and client data fetching  
+✅ **Requirement 13.1**: Metadata generation with title, description, Open Graph  
+✅ **Requirement 13.3**: Structured data (JSON-LD) with Product schema  
+
+## Testing Recommendations
+
+### Manual Testing
+
+1. **SSG Verification**
+   - Build the project: `npm run build`
+   - Check `.next/server/app/products/[slug]` for pre-rendered pages
+   - Verify top 100 products are statically generated
+
+2. **Metadata Verification**
+   - View page source in browser
+   - Check `<head>` for meta tags
+   - Verify Open Graph tags
+   - Test social media sharing
+
+3. **Structured Data Verification**
+   - View page source
+   - Find `<script type="application/ld+json">`
+   - Validate with Google's Rich Results Test
+   - Check schema.org compliance
+
+4. **Currency Switching**
+   - Load product page (should show base currency)
+   - Change currency in selector
+   - Verify prices update without page reload
+   - Check no hydration warnings in console
+
+5. **ISR Verification**
+   - Update product in backend
+   - Wait 60 seconds
+   - Refresh page
+   - Verify changes appear
+
+### Automated Testing
+
+```typescript
+// Example test for metadata generation
+describe('Product Page Metadata', () => {
+  it('should generate correct metadata', async () => {
+    const metadata = await generateMetadata({ params: { slug: 'test-product' } });
+    expect(metadata.title).toBeDefined();
+    expect(metadata.description).toBeDefined();
+    expect(metadata.openGraph).toBeDefined();
+  });
+});
+
+// Example test for static params
+describe('Static Params Generation', () => {
+  it('should generate params for top products', async () => {
+    const params = await generateStaticParams();
+    expect(params.length).toBeGreaterThan(0);
+    expect(params[0]).toHaveProperty('slug');
+  });
+});
+```
+
+## Performance Considerations
+
+1. **Static Generation**: Top 100 products are pre-rendered at build time
+2. **ISR**: Pages revalidate every 60 seconds for fresh data
+3. **React Cache**: Server-side requests are deduplicated within a render
+4. **Client-side Caching**: React Query caches product data with currency in key
+5. **Image Optimization**: Next.js Image component handles optimization
+
+## Future Enhancements
+
+1. **Related Products**: Add similar products section based on tags/category
+2. **Product Reviews**: Integrate review system with structured data
+3. **Variant Images**: Show variant-specific images when variant changes
+4. **Breadcrumbs**: Add dynamic breadcrumbs based on product category
+5. **Share Buttons**: Add social media share buttons
+6. **Recently Viewed**: Track and display recently viewed products
+
+## Troubleshooting
+
+### Hydration Mismatch Errors
+
+**Problem**: Console shows hydration mismatch warnings  
+**Solution**: Ensure `suppressHydrationWarning` is on price elements
+
+### Currency Not Switching
+
+**Problem**: Prices don't update when currency changes  
+**Solution**: Check currency store initialization and query key includes currency
+
+### 404 Errors
+
+**Problem**: Product pages return 404  
+**Solution**: Verify product handle matches exactly, check generateStaticParams
+
+### Metadata Not Showing
+
+**Problem**: Meta tags not appearing in page source  
+**Solution**: Ensure generateMetadata is async and returns Metadata object
+
+## Conclusion
+
+The product detail page implementation follows Next.js 15+ best practices with:
+- Server Components for optimal performance
+- Client Components for interactivity
+- Proper metadata for SEO
+- Structured data for search engines
+- Static generation for popular products
+- ISR for fresh data
+- Currency-aware price display
+
+This implementation satisfies all requirements (2.2, 3.2, 6.4, 13.1, 13.3) and provides a solid foundation for a production-ready e-commerce storefront.

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

@@ -0,0 +1,195 @@
+# DoSwiftly Storefront - shadcn/ui Template
+
+This is a Next.js 15+ storefront template with shadcn/ui components, optimized for DoSwiftly Commerce.
+
+## Features
+
+- ✅ **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
+
+## Getting Started
+
+### 1. Install Dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Configure Environment
+
+Copy `.env.example` to `.env.local` and update:
+
+```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:
+
+```bash
+pnpm run codegen
+```
+
+### 4. Start Development Server
+
+```bash
+pnpm run dev
+```
+
+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
+
+- [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)
+
+## License
+
+UNLICENSED - Internal DoSwiftly template