csgowtf/docs/LOCAL_DEVELOPMENT.md

# Local Development Setup

This guide will help you set up the CS2.WTF frontend for local development.

## Prerequisites

- **Node.js**: v18.x or v20.x (check with `node --version`)
- **npm**: v9.x or higher (comes with Node.js)
- **Backend API**: Either local csgowtfd service OR access to production API

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Environment Configuration

The `.env` file already exists in the project. You can use it as-is or modify it:

**Option A: Use Production API** (Recommended for frontend development)
```env
# Use the live production API - no local backend needed
VITE_API_BASE_URL=https://api.csgow.tf
VITE_API_TIMEOUT=10000
VITE_DEBUG_MODE=true
VITE_ENABLE_ANALYTICS=false
```

**Option B: Use Local Backend** (For full-stack development)
```env
# Use local backend (requires csgowtfd running on port 8000)
VITE_API_BASE_URL=http://localhost:8000
VITE_API_TIMEOUT=10000
VITE_DEBUG_MODE=true
VITE_ENABLE_ANALYTICS=false
```

### 3. Start the Development Server

```bash
npm run dev
```

The frontend will be available at `http://localhost:5173`

You should see output like:
```
[Vite Config] API Proxy target: https://api.csgow.tf
[API Client] Development mode - using Vite proxy
[API Client] Frontend requests: /api/*
[API Client] Proxy target: https://api.csgow.tf

  ➜  Local:   http://localhost:5173/
```

### 4. (Optional) Start Local Backend

Only needed if using `VITE_API_BASE_URL=http://localhost:8000`:

```bash
# In the csgowtfd repository
cd ../csgowtfd
go run cmd/csgowtfd/main.go
```

Or use Docker:
```bash
docker-compose up csgowtfd
```

## How the CORS Proxy Works

The Vite dev server includes a **built-in proxy** that eliminates CORS issues during development:

### Development Mode Flow
```
1. Browser makes request to: http://localhost:5173/api/matches
2. Vite intercepts and proxies to: ${VITE_API_BASE_URL}/matches
3. Backend responds
4. Vite forwards response to browser
```

### Benefits
- ✅ **No CORS errors** - All requests appear same-origin to the browser
- ✅ **Works with any backend** - Local or remote
- ✅ **No backend CORS config needed** - Proxy handles it
- ✅ **Simple configuration** - Just set `VITE_API_BASE_URL`

### Proxy Logs

You'll see detailed proxy activity in the terminal:

```bash
[Proxy] GET /api/matches?limit=6 -> https://api.csgow.tf/matches?limit=6
[Proxy ✓] GET /api/matches?limit=6 -> 200
[Proxy] GET /api/match/123 -> https://api.csgow.tf/match/123
[Proxy ✓] GET /api/match/123 -> 200
```

### Production vs Development

| Mode | API Base URL | CORS |
|------|-------------|------|
| **Development** (`npm run dev`) | `/api` (proxied to `VITE_API_BASE_URL`) | ✅ No issues |
| **Production** (`npm run build`) | `VITE_API_BASE_URL` (direct) | ✅ Backend has CORS enabled |

## Troubleshooting

### No Data Showing / Network Errors

**Problem**: Frontend loads but shows no matches, players show "Failed to load" errors.

**Solutions**:

1. **Check what backend you're using**:
   ```bash
   # Look at your .env file
   cat .env | grep VITE_API_BASE_URL
   ```

2. **If using production API** (`https://api.csgow.tf`):
   ```bash
   # Test if production API is accessible
   curl https://api.csgow.tf/matches?limit=1
   ```
   Should return JSON data. If not, production API may be down.

3. **If using local backend** (`http://localhost:8000`):
   ```bash
   # Test if local backend is running
   curl http://localhost:8000/matches?limit=1
   ```
   If you get "Connection refused", start the backend service.

4. **Check proxy logs**:
   - Look at the terminal running `npm run dev`
   - You should see `[Proxy]` messages showing requests being forwarded
   - If you see `[Proxy Error]`, check the error message

5. **Check browser console**:
   - Open DevTools → Console tab
   - Look for `[API Client]` messages showing proxy configuration
   - Network tab should show requests to `/api/*` (not external URLs)

6. **Restart dev server**:
   ```bash
   # Stop dev server (Ctrl+C)
   npm run dev
   ```

### CORS Errors (Should Not Happen)

If you see CORS errors in the browser console, the proxy isn't working:

**Symptoms**:
- Browser console shows: `CORS policy: No 'Access-Control-Allow-Origin' header`
- Network tab shows requests going to `https://api.csgow.tf` directly (not `/api`)

**Fix**:
1. Verify you're in development mode (not production build)
2. Check API client logs show: `Development mode - using Vite proxy`
3. Restart dev server with clean cache:
   ```bash
   rm -rf .svelte-kit
   npm run dev
   ```

### Port Already in Use

If port 5173 is already in use:

```bash
# Vite will automatically try the next available port
npm run dev

# Or specify a custom port
npm run dev -- --port 3000
```

### Backend Connection Issues

If the backend is on a different host/port, update `.env`:

```env
# Custom backend location
VITE_API_BASE_URL=http://192.168.1.100:8080
```

Then restart the dev server.

## Development Workflow

### 1. Make Changes

Edit files in `src/`. The dev server has hot module replacement (HMR):
- Component changes reload instantly
- Route changes reload the page
- Store changes reload affected components

### 2. Type Checking

Run TypeScript type checking:

```bash
npm run check        # Check once
npm run check:watch  # Watch mode
```

### 3. Linting

```bash
npm run lint         # Check for issues
npm run lint:fix     # Auto-fix issues
npm run format       # Run Prettier
```

### 4. Testing

```bash
# Unit tests
npm run test              # Run once
npm run test:watch        # Watch mode
npm run test:coverage     # Generate coverage report

# E2E tests
npm run test:e2e          # Headless
npm run test:e2e:ui       # Playwright UI
```

## API Endpoints

The backend provides these endpoints (see `docs/API.md` for full details):

- `GET /matches` - List all matches
- `GET /match/:id` - Get match details
- `GET /match/:id/rounds` - Get round economy data
- `GET /match/:id/weapons` - Get weapon statistics
- `GET /match/:id/chat` - Get chat messages
- `GET /player/:id` - Get player profile

### How Requests Work

**In Development** (`npm run dev`):
```
Frontend code:        api.matches.getMatches()
              ↓
API Client:           GET /api/matches
              ↓
Vite Proxy:           GET https://api.csgow.tf/matches
              ↓
Response:             ← Data returned to frontend
```

**In Production** (deployed app):
```
Frontend code:        api.matches.getMatches()
              ↓
API Client:           GET https://api.csgow.tf/matches (direct)
              ↓
Response:             ← Data returned to frontend
```

The API client automatically uses the correct URL based on environment.

## Mock Data (Alternative: No Backend)

If you want to develop without any backend (local or production), enable MSW mocking:

1. Update `.env`:
   ```env
   VITE_ENABLE_MSW_MOCKING=true
   ```

2. Restart dev server

The app will use mock data from `src/mocks/handlers/`.

**Note**: Mock data is limited and may not reflect all features. **Production API is recommended** for most development work.

## Building for Production

```bash
# Build
npm run build

# Preview production build locally
npm run preview
```

The preview server runs on `http://localhost:4173` and uses the production API configuration.

## Environment Variables Reference

| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_API_BASE_URL` | `http://localhost:8000` | Backend API base URL |
| `VITE_API_TIMEOUT` | `10000` | Request timeout (ms) |
| `VITE_ENABLE_LIVE_MATCHES` | `false` | Enable live match polling |
| `VITE_ENABLE_ANALYTICS` | `false` | Enable analytics tracking |
| `VITE_DEBUG_MODE` | `false` | Enable debug logging |
| `VITE_ENABLE_MSW_MOCKING` | `false` | Use mock data instead of API |

## Getting Help

- **Frontend Issues**: Check browser console for errors
- **API Issues**: Check backend logs and proxy output in terminal
- **Type Errors**: Run `npm run check` for detailed messages
- **Build Issues**: Delete `.svelte-kit/` and `node_modules/`, then `npm install`

## Next Steps

- Read `TODO.md` for current development status
- Check `docs/DESIGN.md` for design system documentation
- Review `docs/API.md` for complete API reference
- See `README.md` for project overview