@akinon/projectzero 2.0.0-beta.11 → 2.0.0-beta.13

package/app-template/.github/instructions/default.instructions.md

@@ -0,0 +1,279 @@
+---
+applyTo: '**'
+---
+
+# Project Zero Next.js App - Developer Instructions
+
+## Project Overview
+
+This is a **standalone Project Zero Next.js application** - a headless e-commerce storefront built on top of Akinon Commerce Cloud. This app can be cloned and run independently using the `packages/projectzero` command line tool.
+
+## Key Characteristics
+
+- **Standalone Application**: Can be cloned with `packages/projectzero` CLI and run independently
+- **Next.js 14.2.25**: Uses App Router with dynamic routes
+- **TypeScript**: With relaxed strict mode
+- **E-commerce Focus**: Complete storefront with basket, checkout, payments, user management
+
+## Project Structure
+
+```
+apps/projectzeronext/
+├── src/
+│   ├── app/[commerce]/[locale]/[currency]/  # App Router pages
+│   ├── components/                          # App-specific UI components
+│   ├── views/                              # Page-specific view components
+│   ├── hooks/                              # Custom React hooks
+│   ├── redux/                              # App-specific Redux slices
+│   ├── types/                              # App-specific TypeScript types
+│   ├── utils/                              # Utility functions
+│   ├── settings.js                         # Application configuration
+│   ├── routes/                             # Route definitions
+│   └── middleware.ts                       # Next.js middleware
+├── public/                                 # Static assets
+├── config/                                 # Configuration files
+├── docs/                                   # Documentation
+├── package.json                            # Dependencies and scripts
+├── next.config.mjs                         # Next.js configuration
+├── tailwind.config.js                      # TailwindCSS configuration
+└── tsconfig.json                           # TypeScript configuration
+```
+
+## Core Dependencies
+
+### Essential Packages
+
+- `@akinon/next`: Core e-commerce functionality (version ^1.93.0)
+- `next`: Next.js framework (14.2.25)
+- `react` & `react-dom`: React framework
+- `@reduxjs/toolkit`: State management
+- `next-auth`: Authentication
+- `react-hook-form`: Form handling
+- `yup`: Form validation
+
+### UI & Styling
+
+- `tailwindcss`: Utility-first CSS framework
+- `clsx` & `tailwind-merge`: Conditional styling
+- `lucide-react`: Icon library
+
+### Plugin Packages
+
+The app includes various `pz-*` plugin packages for extended functionality:
+
+- `pz-akifast`, `pz-b2b`, `pz-basket-gift-pack`
+- `pz-bkm`, `pz-checkout-gift-pack`, `pz-click-collect`
+- Payment providers: `pz-apple-pay`, `pz-gpay`, `pz-masterpass`, etc.
+
+## Architecture Patterns
+
+### Route Structure
+
+- Dynamic routes: `/[commerce]/[locale]/[currency]/`
+- App Router with server and client components
+- Middleware for routing and internationalization
+
+### Data Fetching
+
+- **RTK Query** for API calls
+- Server components for initial data
+- Client components with hooks for interactivity
+- Example patterns:
+
+```tsx
+// Server component data fetching
+const basketData = await getBasket();
+
+// Client component hooks
+const { data: basket } = useGetBasketQuery();
+const [addToBasket] = useAddProductToBasketMutation();
+```
+
+### State Management
+
+- **Redux Toolkit** with key slices:
+  - `checkout`: Multi-step checkout flow
+  - `basket`: Shopping cart state
+  - `header`: Navigation state
+  - `root`: Global app state
+- Use `useAppSelector` and `useAppDispatch`
+
+### Component Architecture
+
+```tsx
+// Theme components (app-specific)
+import { Button, Input } from '@theme/components';
+
+// Core components (from @akinon/next)
+import { Image } from '@akinon/next/components/image';
+
+// Plugin system
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+```
+
+### Forms & Validation
+
+Standard pattern with React Hook Form + Yup:
+
+```tsx
+const schema = (t) =>
+  yup.object().shape({
+    email: yup.string().email().required(t('error.required')),
+    password: yup.string().min(6).required(t('error.required'))
+  });
+
+const {
+  register,
+  handleSubmit,
+  formState: { errors }
+} = useForm({
+  resolver: yupResolver(schema(t))
+});
+```
+
+## E-commerce Features
+
+### Core Functionality
+
+- **Product Catalog**: Browse, search, filter products
+- **Basket Management**: Add/remove items, quantity updates
+- **Checkout Flow**: Multi-step process (auth → shipping → payment → confirmation)
+- **User Accounts**: Registration, login, order history
+- **Payment Integration**: Multiple payment providers
+- **Order Management**: Track orders, view history
+
+### Internationalization
+
+- Multi-language support with `useLocalization()` hook
+- Dynamic locale routing: `/[locale]/`
+- Translation keys: `t('checkout.auth.title')`
+- Settings configuration in `src/settings.js`
+
+### Authentication
+
+- NextAuth.js integration
+- Session management with `useSession()`
+- Protected routes via middleware
+- User account features
+
+## Development Guidelines
+
+### File Naming & Structure
+
+- Components: PascalCase (`ProductCard.tsx`)
+- Pages: kebab-case in App Router directories
+- Hooks: camelCase starting with `use` (`useBasket.ts`)
+- Types: PascalCase with descriptive names (`ProductType.ts`)
+
+### Import Conventions
+
+```tsx
+// Path aliases (configured in tsconfig.json)
+import { Button } from '@theme/components'; // App components
+import { Image } from '@akinon/next/components'; // Core components
+import { useLocalization } from '@akinon/next/hooks'; // Core hooks
+import { ProductType } from '@akinon/next/types'; // Core types
+import { routes } from '@root/routes'; // App routes
+```
+
+### Styling Guidelines
+
+- **TailwindCSS** for all styling
+- Use `clsx` and `twMerge` for conditional classes
+- Responsive design: mobile-first approach
+- Theme customization in `tailwind.config.js`
+
+### Performance Best Practices
+
+- Lazy loading with `LazyComponent`
+- Next.js `Image` component for optimized images
+- Code splitting with dynamic imports
+- Intersection Observer for viewport-based loading
+
+## Development Commands
+
+```bash
+# Development
+yarn dev              # Start development server
+yarn build            # Build for production
+yarn start            # Start production server
+
+# Code Quality
+yarn lint             # Run ESLint
+yarn lint:fix         # Fix ESLint issues
+yarn type-check       # TypeScript type checking
+
+# Testing
+yarn test             # Run Jest tests
+yarn test:watch       # Run tests in watch mode
+```
+
+## Configuration Files
+
+### Key Config Files
+
+- `next.config.mjs`: Next.js configuration
+- `tailwind.config.js`: TailwindCSS theme and plugins
+- `src/settings.js`: App-specific settings (commerce, locales, etc.)
+- `src/middleware.ts`: Route handling and internationalization
+- `package.json`: Dependencies and scripts
+
+### Environment Variables
+
+Configure in `.env.local`:
+
+- `NEXTAUTH_SECRET`: Authentication secret
+- `NEXTAUTH_URL`: Application URL
+- Commerce API endpoints
+- Payment provider configurations
+
+## Plugin System
+
+### Using Plugins
+
+```tsx
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+// Conditional plugin rendering
+<PluginModule component={Component.BasketGiftPack} props={{ basket }} />;
+```
+
+### Available Plugins
+
+- **Payment**: Apple Pay, Google Pay, BKM, Masterpass
+- **Checkout**: Gift packs, click & collect, one-click checkout
+- **Business**: B2B features, multi-basket, saved cards
+- **Regional**: Tabby, Tamara (MENA region)
+
+## Important Notes
+
+### Critical Middleware
+
+- **Never remove** `withPzDefault` middleware - essential for app functionality
+- Middleware handles routing, locale detection, commerce resolution
+
+### State Management
+
+- Checkout uses multi-step Redux flow
+- Basket state syncs with backend APIs
+- User session integrates with NextAuth
+
+### SEO & Analytics
+
+- GTM integration for e-commerce tracking
+- Server-side rendering for SEO
+- Structured data for products
+
+### Deployment
+
+- Can be deployed standalone
+- Supports various hosting platforms
+- Environment-specific configurations
+
+When working with this app, always consider:
+
+1. **E-commerce context**: Every feature impacts the shopping experience
+2. **Plugin architecture**: Use modular approach for features
+3. **Internationalization**: Support multiple languages/regions
+4. **Performance**: Optimize for mobile commerce
+5. **Standalone nature**: App should work independently when cloned

package/app-template/.github/instructions/edge-cases.instructions.md

@@ -0,0 +1,73 @@
+---
+applyTo: '**'
+---
+
+# Edge Cases & Troubleshooting Instructions
+
+## Overview
+
+This document contains common edge cases, bugs, and troubleshooting steps encountered in Project Zero Next.js development. These are real-world issues that have caused development delays and should be checked first when similar problems occur.
+
+## Checkout Flow Edge Cases
+
+### 1. Order Selection Page Request Timing
+
+**Problem:** `orderselectionpage` request should NOT be called after `walletselectionpage` or `walletpaymentpage` requests.
+
+This causes checkout flow to break after wallet payment steps, order selection shows incorrect state, and payment flow gets reset unexpectedly. After `walletselectionpage` or `walletpaymentpage` requests are made, `orderselectionpage` request should not be called. Always check the sequence of checkout API calls.
+
+### 2. Guest Login with URL Parameters
+
+**Problem:** Adding `?page=IndexPage` to checkout URLs breaks guest login functionality.
+
+Guest login fails on checkout URLs with `?page=IndexPage` but works fine without the parameter. This parameter interferes with authentication middleware routing. Avoid adding unnecessary URL parameters to checkout flows.
+
+### 3. Agreement Error After 3D Payment Redirect
+
+**Problem:** "You must accept agreement to continue" error appears after 3D payment or redirections, but the issue is NOT related to agreements.
+
+Agreement error occurs after successful 3D payment and checkout flow breaks after external redirections. The error message is misleading - actually `preOrder` data gets reset/lost during payment redirections. Don't assume agreement errors are actually about agreements.
+
+### 4. Address Visibility with fetchCheckout
+
+**Problem:** When `fetchCheckout` request includes `page=IndexPage` parameter, addresses don't show in checkout and the entire flow breaks.
+
+Addresses are missing from checkout page, shipping options don't load, and checkout flow is completely broken. Avoid adding unnecessary parameters to core checkout requests and validate that all checkout data loads properly.
+
+## Plugin & Configuration Edge Cases
+
+### 5. Attribute-Based Shipping Options Typo
+
+**Problem:** `attribute_based_shipping_options` was incorrectly entered as `atribute_based` (missing 't') in brand configurations.
+
+Shipping options don't work for specific brands and debugging is difficult because the setting exists but is misspelled. This can cause days of debugging. Always double-check configuration property names.
+
+### 6. Apple Pay Plugin Configuration
+
+**Problem:** Apple Pay can work as both `confirmation` and `wallet` payment types, but for the plugin to work properly, it should NOT be configured as `confirmation` type.
+
+Apple Pay flow breaks in certain scenarios, payment confirmation issues occur, and plugin conflicts with checkout flow. Always configure Apple Pay as wallet type.
+
+## Build & Development Edge Cases
+
+### 7. Build Failures Due to yarn.lock Corruption
+
+**Problem:** Build fails with apparent TypeScript errors in `@akinon/next` components, but the real issue is a corrupted `yarn.lock` file.
+
+Build fails with nonsensical type errors, components from `@akinon/next` are flagged with errors, and multiple versions of the same package exist in lock file.
+
+```bash
+# Check for duplicate packages in yarn.lock
+yarn list --pattern "@akinon/next" --depth=0
+
+# If multiple versions exist, clean up
+rm yarn.lock
+rm -rf node_modules
+yarn install
+```
+
+Regularly check `yarn.lock` for duplicate dependencies and use `yarn dedupe` after adding new packages.
+
+---
+
+**Remember:** Edge cases often have misleading error messages. Always investigate the root cause rather than fixing symptoms. The most time-consuming bugs are usually simple configuration or timing issues.