---
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