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

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)

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

# 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

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:

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

Or use Docker:

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:

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

   # Look at your .env file
   cat .env | grep VITE_API_BASE_URL
   

2. If using production API (https://api.csgow.tf):

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

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

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

  rm -rf .svelte-kit
  npm run dev
  

Port Already in Use

If port 5173 is already in use:

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

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

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

3. Linting

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

4. Testing

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

   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

# 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