my_openplace/frontend-src/QUICKSTART.md

Quick Start Guide

Setup (5 minutes)

1. Install Dependencies

cd frontend-src
pnpm install

2. Configure Environment

cp .env.example .env

Edit .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

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

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

PUBLIC_ENABLE_TURNSTILE=false

• Login works immediately, no captcha
• Perfect for local development

Production (With Captcha)

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

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

<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

<script>
  import { t } from '$lib/i18n';
</script>

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

Create a New Page

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

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

pnpm install

TypeScript errors

pnpm check

Vite not starting

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
• 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 - This file
• BUILD.md - Build configuration & deployment
• README.md - Overview
• IMPLEMENTATION_NOTES.md - Technical details
• BUILD_STATUS.md - What's done and what's next