FangDash Docs

TL;DR - Requires Node.js >= 24, Bun 1.3.10, a Cloudflare account, and a Twitch app - Clone → install → create D1 database → copy env files → bun dev - Web runs at localhost:3000, API at localhost:8787

Estimated time: ~10 minutes

This guide is for developers who want to run FangDash locally or contribute to the project.

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	>= 24
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 install

Step 2 of 4 — Set Up the Database

Create a Cloudflare D1 database:

bunx wrangler d1 create fangdash-db

The output will look 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/). This is already configured in wrangler.toml — you only need to update the database_id.

Then run migrations:

bunx wrangler d1 migrations apply fangdash-db --local

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

Never 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

Generate a strong secret with: openssl rand -base64 32 — paste the output as your BETTER_AUTH_SECRET.

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 this, sign-in will fail with a redirect error.

To find your Twitch Client ID and Client Secret:

Go to the Twitch Developer Console
Click on 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:8787

Step 4 of 4 — Start Development

bun dev

The web app runs at http://localhost:3000 and the API at http://localhost:8787.

You're all set! Your local FangDash instance is running. Head to localhost:3000 and sign in with Twitch to start playing.

Available Scripts

Command	Description
`bun dev`	Start all apps in development mode
`bun build`	Build all packages and apps
`bun test`	Run all tests with Vitest
`bun test:coverage`	Run tests with coverage report
`bun typecheck`	Type-check all packages
`bun lint`	Lint all packages
`bun lint:fix`	Lint with auto-fix
`bun check`	Run ESLint + Prettier check
`bun format`	Format all files with Prettier
`bun format:check`	Check formatting without writing
`bun clean`	Remove all build artifacts

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 all four variables (`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET`) are 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 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
"Cannot find module" on `bun dev`	Dependencies not installed	Run `bun install` from the repo root

Developer Setup