Developer Setup
Run FangDash locally — clone the repo, install with Bun, create a Cloudflare D1 database, set env vars, and start the dev server on localhost
TL;DR — You need Node.js >= 20, Bun 1.3.10, a Cloudflare account, and a Twitch app. Clone →
install → create D1 → copy env files → bun run dev. Web runs at localhost:3000, API at
localhost:8787.
This guide is for developers who want to run FangDash locally or contribute to the project. FangDash is a Turborepo monorepo managed with Bun workspaces, so a single install and one dev command bring up every app at once.
Prerequisites
You need a Cloudflare account (for the D1 database) and a Twitch Developer application (for OAuth) before you can run FangDash locally.
| Requirement | Version |
|---|---|
| Node.js | >= 20 |
| Bun | 1.3.10 (curl -fsSL https://bun.sh/install | bash) |
| Cloudflare account | Free tier works |
| Twitch Developer app | dev.twitch.tv/console |
Step 1 of 4 — Clone and install
git clone https://github.com/MrDemonWolf/fangdash.git
cd fangdash
bun installOne bun install at the repo root wires up every workspace: apps/web, apps/api, apps/party, apps/docs, and the shared packages/.
Step 2 of 4 — Set up the database
FangDash stores everything in a single Cloudflare D1 (SQLite) database. Create it with:
bunx wrangler d1 create fangdash-dbThe output looks something like this:
✅ Successfully created DB 'fangdash-db'
[[d1_databases]]
binding = "DB"
database_name = "fangdash-db"
database_id = "abc12345-xxxx-xxxx-xxxx-xxxxxxxxxxxx"Copy the database_id value and paste it into the [[d1_databases]] block in apps/api/wrangler.toml:
[[d1_databases]]
binding = "DB"
database_name = "fangdash-db"
database_id = "abc12345-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # ← replace this
migrations_dir = "drizzle"FangDash uses drizzle as the migrations directory (not migrations/). That's already configured
in wrangler.toml — you only need to update the database_id.
Then apply the migrations to your local database:
bunx wrangler d1 migrations apply fangdash-db --localThis creates all 9 tables — the Better Auth tables (user, session, account, verification) plus the game tables (player, score, player_skin, player_achievement, race_history).
If migrations fail, make sure you've logged into Cloudflare first with bunx wrangler login.
Step 3 of 4 — Configure environment variables
Copy the example files from the repo root:
cp apps/api/.dev.vars.example apps/api/.dev.vars
cp apps/web/.env.example apps/web/.env.localNever commit .dev.vars or .env.local — they contain secrets. Both files are already in
.gitignore.
Fill in apps/api/.dev.vars:
BETTER_AUTH_SECRET=your-secret-here
BETTER_AUTH_URL=http://localhost:8787
TWITCH_CLIENT_ID=your-twitch-client-id
TWITCH_CLIENT_SECRET=your-twitch-client-secret
WEB_URL=http://localhost:3000
# Shared HMAC secret for short-lived PartyKit race connection tokens.
# Needed for multiplayer — must match apps/party/.env (see below).
RACE_TOKEN_SECRET=your-race-token-secretGenerate strong secrets with openssl rand -base64 32 for BETTER_AUTH_SECRET, and openssl rand -hex 32 for RACE_TOKEN_SECRET.
Multiplayer race auth — the PartyKit server verifies race connections with the same
RACE_TOKEN_SECRET. Create apps/party/.env with RACE_TOKEN_SECRET=<same-value>, or real-time
races will reject every connection. The two values must be identical.
Twitch OAuth redirect URL — In your Twitch Developer Console
app settings, add http://localhost:8787/api/auth/callback/twitch as an OAuth Redirect URL.
Without it, sign-in fails with a redirect error. Twitch is the only sign-in provider.
To find your Twitch Client ID and Client Secret:
- Go to the Twitch Developer Console
- Click your application (or create one)
- The Client ID is shown on the app overview page
- Click New Secret to generate a Client Secret (it's only shown once — copy it immediately)
Fill in apps/web/.env.local:
NEXT_PUBLIC_API_URL=http://localhost:8787Step 4 of 4 — Start development
bun run devThis starts all four apps: web at http://localhost:3000, API at http://localhost:8787, the PartyKit race server on 1999, and these docs on 3001.
You're all set. Head to localhost:3000 and sign in with Twitch to save scores and play
multiplayer — solo play works without an account.
Available scripts
Run these from the repo root. Use bun run <script> so Bun invokes the package script rather than its built-in build/test commands.
| Command | Description |
|---|---|
bun run dev | Start all apps in development mode |
bun run build | Build all packages and apps |
bun run test | Run all tests with Vitest |
bun run test:coverage | Run tests with a coverage report |
bun run typecheck | Type-check all packages |
bun run lint | Lint all packages |
bun run lint:fix | Lint with auto-fix |
bun run check | Run ESLint + Prettier check |
bun run format | Format all files with Prettier |
bun run format:check | Check formatting without writing |
bun run clean | Remove all build artifacts |
bun run ship | Deploy api, web, and party to Cloudflare |
Troubleshooting
| Error / Symptom | Likely Cause | Fix |
|---|---|---|
D1_ERROR or "database not found" | database_id in wrangler.toml doesn't match your D1 database, or migrations haven't been run | Double-check the ID from bunx wrangler d1 list and re-run bunx wrangler d1 migrations apply fangdash-db --local |
| "Auth not configured" or 503 from API | Missing or incorrect values in apps/api/.dev.vars | Ensure BETTER_AUTH_SECRET, BETTER_AUTH_URL, TWITCH_CLIENT_ID, and TWITCH_CLIENT_SECRET are all set |
| CORS errors in the browser console | NEXT_PUBLIC_API_URL in apps/web/.env.local doesn't match the actual API URL | Verify the URL is http://localhost:8787 (no trailing slash) and restart bun run dev after changing env files |
| Blank page or error after Twitch sign-in | OAuth Redirect URL not registered in Twitch Developer Console | Add http://localhost:8787/api/auth/callback/twitch as a redirect URL in your Twitch app settings |
| Races reject every connection | RACE_TOKEN_SECRET differs between apps/api/.dev.vars and apps/party/.env | Set the exact same value in both files, then restart bun run dev |
"Cannot find module" on bun run dev | Dependencies not installed | Run bun install from the repo root |
Getting Started
Sign in with Twitch, play your first solo run, check your score on the leaderboard, and join a live wolf race in FangDash.
Self-Host FangDash on Cloudflare
Deploy your own FangDash instance to Cloudflare Workers and D1 — wire up the API, web app, and PartyKit multiplayer server with wrangler and bun.