232 lines
4.4 KiB
Markdown
232 lines
4.4 KiB
Markdown
# 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
|