# ⚡ ReactWare

Ultra-fast headless storefront for Shopware 6, built with Next.js + React.
**Goal: Google PageSpeed 100.**

## 📚 Documentation

- **[Complete Project Guide](docs/GUIDE.md)** — architecture, full feature list, every environment variable, project structure, theming, i18n, CAPTCHA, caching, and troubleshooting.
- **[Server Setup & Deployment Guide](docs/DEPLOYMENT.md)** — deploy to Vercel, a Node/VPS server (PM2 + Nginx), or Docker, with a post-deploy checklist.

The quick start below gets you running locally; the guides above cover everything else.

## For Shopware Developers (New to React)

If you know Shopware 6 but not React, here's a quick mapping:

| Shopware (Twig)              | React (Next.js)                    |
| ---------------------------- | ---------------------------------- |
| `base.html.twig`             | `src/app/layout.tsx`               |
| `product-box.html.twig`      | `src/components/product/ProductCard.tsx` |
| `buy-widget.html.twig`       | `src/components/product/AddToCartButton.tsx` |
| `header.html.twig`           | `src/components/layout/Header.tsx`  |
| `footer.html.twig`           | `src/components/layout/Footer.tsx`  |
| Shopware CartService         | `src/lib/cart-context.tsx`          |
| SalesChannelApiClient        | `src/lib/shopware-api.ts`           |
| `{% block %}` in Twig        | React Components (reusable pieces)  |
| Twig `{{ variables }}`       | JSX `{variables}`                   |
| StorefrontController routes  | `src/app/*/page.tsx` files          |

## Quick Start

### Prerequisites
- **Node.js 18+** installed ([download](https://nodejs.org))
- A **Shopware 6 shop** with a **Headless Sales Channel**

### Step 1: Install Node.js (if you don't have it)
```bash
# Check if you have Node.js
node --version

# If not installed, download from https://nodejs.org
# Or use nvm (recommended):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
```

### Step 2: Create Headless Sales Channel in Shopware
1. Go to your Shopware Admin
2. **Settings → Sales Channels → + Add Sales Channel → Headless**
3. Configure: name, language, currency, domains
4. Copy the **API Access Key** (you'll need it)

### Step 3: Setup the Project
```bash
# Clone or copy this project
cd reactware

# Install dependencies (like composer install in PHP)
npm install

# Copy environment config
cp .env.example .env.local

# Edit .env.local with your Shopware details:
# NEXT_PUBLIC_SHOPWARE_URL=https://your-shop.com
# NEXT_PUBLIC_SHOPWARE_ACCESS_KEY=SWSC-your-key-here
```

### Step 4: Run Development Server
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) — you should see your products!

### Step 5: Build for Production
```bash
npm run build
npm start
```

## Project Structure

```
reactware/
├── src/
│   ├── app/                    # Pages (like Controller routes)
│   │   ├── layout.tsx          # Root layout (base.html.twig)
│   │   ├── page.tsx            # Homepage
│   │   ├── products/
│   │   │   ├── page.tsx        # Product listing page
│   │   │   └── [id]/
│   │   │       └── page.tsx    # Product detail page
│   │   └── about/
│   │       └── page.tsx        # About page
│   ├── components/             # Reusable UI pieces
│   │   ├── layout/
│   │   │   ├── Header.tsx
│   │   │   └── Footer.tsx
│   │   ├── product/
│   │   │   ├── ProductCard.tsx  # Product box in grid
│   │   │   └── AddToCartButton.tsx
│   │   ├── cart/
│   │   │   └── CartDrawer.tsx   # Slide-in cart
│   │   └── ui/
│   │       └── SearchBar.tsx    # Search with autocomplete
│   ├── lib/                    # Services & utilities
│   │   ├── shopware-api.ts     # ALL Shopware API calls
│   │   └── cart-context.tsx    # Cart state management
│   └── types/                  # TypeScript types
├── public/                     # Static files (favicon, etc.)
├── .env.example                # Environment template
├── .env.local                  # Your local config (git-ignored)
├── next.config.js              # Next.js settings
├── tailwind.config.js          # Tailwind CSS settings
└── package.json                # Dependencies
```

## Key Concepts for Shopware Devs

### Server vs Client Components
- **Server Components** (default): Render on server, send HTML. No JavaScript sent to browser. FAST!
- **Client Components** (`'use client'`): Run in browser. Needed for interactivity (clicks, forms, state).

**Rule of thumb**: Only use `'use client'` when you need `useState`, `onClick`, or browser APIs.

### How Data Flows
```
1. User visits /products
2. Next.js server calls Shopware Store API
3. Server renders HTML with product data
4. Browser receives ready HTML (no loading spinner!)
5. Interactive parts (cart, search) hydrate with JavaScript
```

### Adding New Pages
Create a file at `src/app/your-page/page.tsx`:
```tsx
export default function YourPage() {
  return <h1>Hello!</h1>;
}
```
That's it — Next.js automatically creates the route `/your-page`.

## What's Included

- [x] Homepage with hero + product grid
- [x] Product listing page (PLP)
- [x] Product detail page (PDP)
- [x] Cart (add, update, remove, drawer)
- [x] Search with autocomplete
- [x] Responsive design (mobile + desktop)
- [x] SEO metadata
- [x] Server-side rendering

## What's NOT Included (Yet)

- [ ] Checkout flow
- [ ] Customer login/register
- [ ] Category navigation (from Shopware)
- [ ] CMS page rendering
- [ ] Wishlist
- [ ] Filters and sorting on PLP
- [ ] Payment integration
- [ ] Multi-language support

## Deployment

See the **[Server Setup & Deployment Guide](docs/DEPLOYMENT.md)** for full instructions covering:

- **Vercel** (easiest, fully managed)
- **Node.js server (VPS)** with PM2 + Nginx + Let's Encrypt
- **Docker** (multi-stage build)
- Production environment variables and a post-deploy checklist

## Troubleshooting

**Products not loading?**
- Check your `.env.local` values
- Make sure the Headless Sales Channel is active
- Check CORS settings in Shopware (allow your frontend domain)

**CORS errors?**
In Shopware Admin → Settings → System → Sales Channel → Domain:
Add your frontend URL (e.g., `http://localhost:3000`)

---

Built with ❤️ for the Shopware community.
Powered by Next.js 14, React 18, and Tailwind CSS.