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 v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
```

### 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 SvelteKit API Routes Work

All API requests go through **SvelteKit server routes** which proxy to the backend. This works consistently in all environments.

### Request Flow (All Environments)

```
1. Browser makes request to: http://localhost:5173/api/matches
2. SvelteKit routes to: src/routes/api/[...path]/+server.ts
3. Server handler reads VITE_API_BASE_URL environment variable
4. Server fetches from backend: ${VITE_API_BASE_URL}/matches
5. Backend responds
6. Server handler forwards response to browser
```

### Benefits

- ✅ **No CORS errors** - All requests are server-side
- ✅ **Works in all environments** - Dev, preview, and production
- ✅ **Single code path** - Same behavior everywhere
- ✅ **Easy backend switching** - Change one environment variable
- ✅ **Future-proof** - Can add caching, rate limiting, auth later
- ✅ **Backend URL not exposed** - Hidden from client

### Switching Between Backends

Simply update `.env` and restart the dev server:

```bash
# Use production API
echo "VITE_API_BASE_URL=https://api.csgow.tf" > .env
npm run dev

# Use local backend
echo "VITE_API_BASE_URL=http://localhost:8000" > .env
npm run dev
```

### Development vs Production

| Mode                             | Request Flow                                   | Backend URL From               |
| -------------------------------- | ---------------------------------------------- | ------------------------------ |
| **Development** (`npm run dev`)  | Browser → `/api/*` → SvelteKit Route → Backend | `.env` → `VITE_API_BASE_URL`   |
| **Production** (`npm run build`) | Browser → `/api/*` → SvelteKit Route → Backend | Build-time `VITE_API_BASE_URL` |

**Note**: The flow is identical in both modes - this is the key advantage over the old Vite proxy approach.

## 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 browser console**:
   - Open DevTools → Console tab
   - Look for `[API Route]` error messages from the server route handler
   - Network tab should show requests to `/api/*` (not external URLs)
   - Check if requests return 503 (backend unreachable) or 500 (server error)

5. **Check server logs**:
   - Look at the terminal running `npm run dev`
   - Server route errors will appear with `[API Route] Error fetching...`
   - This will show you the exact backend URL being requested

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

### CORS Errors (Should Never Happen)

CORS errors should be impossible with SvelteKit server routes since all requests are server-side.

**If you somehow see CORS errors:**

- This means the API client is bypassing the `/api` routes
- Check that `src/lib/api/client.ts` has `API_BASE_URL = '/api'`
- Verify `src/routes/api/[...path]/+server.ts` exists
- Clear cache and restart:
  ```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

**All Environments** (dev, preview, production):

```
Frontend code:        api.matches.getMatches()
              ↓
API Client:           GET /api/matches
              ↓
SvelteKit Route:      src/routes/api/[...path]/+server.ts
              ↓
Server Handler:       GET ${VITE_API_BASE_URL}/matches
              ↓
Response:             ← Data returned to frontend
```

The request flow is identical in all environments. The only difference is which backend URL `VITE_API_BASE_URL` points to:

- Development: Usually `https://api.csgow.tf` (production API)
- Local full-stack: `http://localhost:8000` (local backend)
- Production: `https://api.csgow.tf` (or custom backend URL)

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