# Quick Start Guide

## Setup (5 minutes)

### 1. Install Dependencies
```bash
cd frontend-src
pnpm install
```

### 2. Configure Environment
```bash
cp .env.example .env
```

Edit `.env`:
```env
PUBLIC_API_URL=http://localhost:3000
PUBLIC_SEASON=s1
PUBLIC_ENABLE_TURNSTILE=false
PUBLIC_TURNSTILE_SITE_KEY=0x4AAAAAABpqJe8FO0N84q0F
```

**Important**: Set `PUBLIC_ENABLE_TURNSTILE=false` for local development to skip captcha.

### 3. Run Development Server
```bash
pnpm dev
```

Open http://localhost:5173

The dev server proxies API calls to `http://localhost:3000` (your backend).

---

## Building for Production

### Build and Deploy to Parent Backend

```bash
# Builds to ../frontend/ directory
pnpm build

# Start parent backend
cd ..
pnpm start

# Open http://localhost:3000
```

The build automatically outputs to the parent backend's static folder.

---

## Turnstile Configuration

### Development (No Captcha)
```env
PUBLIC_ENABLE_TURNSTILE=false
```
- Login works immediately, no captcha
- Perfect for local development

### Production (With Captcha)
```env
PUBLIC_ENABLE_TURNSTILE=true
PUBLIC_TURNSTILE_SITE_KEY=your_site_key_here
```
- Cloudflare Turnstile loads on login
- Protects against bots

---

## What You'll See

### Home Page (`/`)
- Redirects to `/join` if not logged in
- Shows canvas placeholder if authenticated

### Login Page (`/join`)
- Google OAuth button
- Twitch OAuth button
- Cloudflare Turnstile captcha (if enabled)

### After Login
- Header with user avatar
- Dropdown menu (Profile, Alliance, Leaderboard, Store, Logout)
- Toast notifications for actions

---

## Testing Authentication

**With Turnstile disabled** (recommended for dev):
1. Click "Login with Google" or "Login with Twitch"
2. Authorize with OAuth provider
3. Backend sets JWT cookie (`j`)
4. Redirected back to home page
5. User data loaded automatically

**With Turnstile enabled**:
1. Complete Turnstile captcha first
2. Then click OAuth button
3. ... rest same as above

---

## Common Tasks

### Make an API Call
```typescript
import { api } from '$lib/api/client';

const user = await api.getMe();
const alliance = await api.getAlliance();
await api.paintPixels('s1', 0, 0, {
  colors: [7],
  coords: [[100, 100]]
});
```

### Use a Store
```svelte
<script>
  import { currentUser } from '$lib/stores/user';
  import { toast } from '$lib/stores/toast';
</script>

{#if $currentUser}
  <p>Hello, {$currentUser.name}!</p>
  <button on:click={() => toast.success('Clicked!')}>
    Click me
  </button>
{/if}
```

### Translate Text
```svelte
<script>
  import { t } from '$lib/i18n';
</script>

<h1>{$t('login')}</h1>
<p>{$t('loginWith', { provider: 'Google' })}</p>
```

### Create a New Page
```svelte
<!-- src/routes/my-page/+page.svelte -->
<script>
  import Header from '$lib/components/layout/Header.svelte';
</script>

<svelte:head>
  <title>My Page</title>
</svelte:head>

<Header />
<main class="container mx-auto p-4">
  <h1>My Page</h1>
</main>
```

---

## Available Scripts

```bash
pnpm dev       # Start dev server (hot reload)
pnpm build     # Build for production → ../frontend/
pnpm preview   # Preview production build
pnpm check     # Type check
```

---

## Troubleshooting

### "Module not found" errors
```bash
pnpm install
```

### TypeScript errors
```bash
pnpm check
```

### Vite not starting
```bash
rm -rf node_modules .svelte-kit
pnpm install
pnpm dev
```

### API calls fail
- Check `PUBLIC_API_URL` in `.env`
- Ensure backend is running on `http://localhost:3000`
- Check browser console for CORS errors

### OAuth redirect fails
- Backend must handle `/auth/google` and `/auth/twitch`
- If Turnstile is enabled, check token is being sent
- Verify backend sets `j` cookie correctly

### Turnstile not showing
- Check `PUBLIC_ENABLE_TURNSTILE=true` (string, not boolean)
- Verify `PUBLIC_TURNSTILE_SITE_KEY` is correct
- Look for script errors in browser console

---

## Resources

- **Full Build Guide**: [BUILD.md](BUILD.md)
- **SvelteKit Docs**: https://kit.svelte.dev/docs
- **DaisyUI Components**: https://daisyui.com/components/
- **TailwindCSS**: https://tailwindcss.com/docs
- **Leaflet**: https://leafletjs.com/

---

## Questions?

See full documentation:
- [QUICKSTART.md](QUICKSTART.md) - This file
- [BUILD.md](BUILD.md) - Build configuration & deployment
- [README.md](README.md) - Overview
- [IMPLEMENTATION_NOTES.md](IMPLEMENTATION_NOTES.md) - Technical details
- [BUILD_STATUS.md](BUILD_STATUS.md) - What's done and what's next