Brackeys is the community web app for the Brackeys Discord. This repo is a single TanStack Start application that powers:

• the home / jam landing page
• the command center
• developer profiles
• the collab board

This README is the repo-level source of truth for local setup and day-to-day development. The old starter README is intentionally replaced because it no longer matched the codebase.

• TanStack Start + Vite
• React 19
• TanStack Router, Query, Store, and Devtools
• Tailwind CSS v4
• Biome
• Drizzle ORM + PostgreSQL
• Better Auth
• ORPC
• Storybook

• / home / jam landing page
• /command-center command and macro docs
• /profile sign-in gate and profile entry
• /profile/:userId public profile view and owner edit flow
• /collab collab browse flow
• /collab/new collab post creation
• /collab/:postId collab post detail
• /oauth/github/callback GitHub account-link callback
• /oauth/itchio/callback itch.io link callback
• /api/auth/* Better Auth endpoints
• /api/rpc/* ORPC endpoints

src/
  components/
    collab/
    home/
    layout/
    profile/
    ui/
  db/
  lib/
  orpc/
  routes/
drizzle/
.storybook/

Important files:

• src/routes/__root.tsx: shell, background, command palette, layout
• src/db/schema.ts: app schema
• src/lib/auth.ts: Better Auth provider config
• src/orpc/router/*: typed server procedures
• drizzle.config.ts: Drizzle config

• Bun
• PostgreSQL
• Discord OAuth app credentials

Optional but relevant depending on what you are working on:

• GitHub OAuth app credentials
• itch.io client ID
• Strapi instance for collab image uploads
• MinIO credentials for profile image uploads
• Sentry DSN

1. Install dependencies.

bun install

2. Create local env vars.

Copy-Item .env.example .env.local

3. Fill in the required secrets in .env.local.

Minimum required for most local work:

• DATABASE_URL
• BETTER_AUTH_URL
• BETTER_AUTH_SECRET
• DISCORD_CLIENT_ID
• DISCORD_CLIENT_SECRET
• DISCORD_GUILD_ID

4. Apply database schema.

Only the user should ever run bun run db:generate, bun run db:migrate, or bun run db:push. Agents should update schema and migration files, but the user remains the only operator for those commands.

For an existing migration flow:

bun run db:migrate

For fast local iteration against an empty local database:

bun run db:push

5. Start the dev server.

bun run dev

The app runs on http://localhost:3000.

README only documents variables that are actually referenced in the repo today.

• DATABASE_URL: Postgres connection string
• BETTER_AUTH_URL: local app URL, usually http://localhost:3000
• BETTER_AUTH_SECRET: Better Auth secret
• DISCORD_CLIENT_ID: Discord OAuth client ID
• DISCORD_CLIENT_SECRET: Discord OAuth client secret
• DISCORD_GUILD_ID: guild used for member role/profile enrichment

• GITHUB_CLIENT_ID: GitHub account linking
• GITHUB_CLIENT_SECRET: GitHub account linking
• VITE_ITCHIO_CLIENT_ID: itch.io linking flow
• VITE_STRAPI_URL: Strapi-backed uploads / demo content
• MINIO_ENDPOINT: MinIO server URL, for example https://your-minio-host.up.railway.app
• MINIO_PUBLIC_BASE_URL: public base URL used to render stored objects
• MINIO_BUCKET: bucket name for uploaded profile project images
• MINIO_ACCESS_KEY: MinIO access key
• MINIO_SECRET_KEY: MinIO secret key

• VITE_APP_TITLE: client title override
• SERVER_URL: server-side absolute URL override
• VITE_SENTRY_DSN: Sentry client/server instrumentation

If you have access to the Railway project, you can pull environment variables directly from Railway instead of maintaining .env.local manually.

https://docs.railway.com/cli#installing-the-cli

npm i -g @railway/cli
# or MacOS
brew install railway
# or Linux/WSL
bash <(curl -fsSL cli.new)

railway login
railway link

The interactive prompt will ask you to select the workspace, project, environment, and service.

railway environment       # list available environments
railway environment dev   # switch to dev

Use the railway:* scripts to run any command with Railway-injected environment variables:

vp run railway:dev          # dev server with Railway env vars
vp run railway:build        # production build
vp run railway:db:migrate   # run migrations against Railway database
vp run railway:db:studio    # open Drizzle Studio against Railway database

You can also pass -s <service> and -e <environment> flags inline:

railway run -e staging -- vp dev --port 3000

The standard bun run dev / vp run dev workflow with .env.local continues to work for developers who do not need Railway CLI.

bun run dev
bun run build
bun run preview
bun run start

bun run db:generate
bun run db:migrate
bun run db:push
bun run db:pull
bun run db:studio

bun run lint
bun run format
bun run check
bun run test

bun run storybook
bun run build-storybook

bun run db:generate, bun run db:migrate, and bun run db:push are user-only commands. Do not have agents execute them.

The app version displayed in the hero is driven by package.json's version field via Vite's define (__APP_VERSION__).

A GitHub Actions workflow (.github/workflows/version-bump.yml) auto-bumps the prerelease number on every push to main:

0.0.0-alpha.127 → 0.0.0-alpha.128 → 0.0.0-alpha.129 …

For bigger jumps, update manually:

npm version preminor --preid=beta --no-git-tag-version  # → 0.1.0-beta.0
npm version minor --no-git-tag-version                   # → 0.1.0
npm version premajor --preid=alpha --no-git-tag-version  # → 1.0.0-alpha.0

CI will continue auto-incrementing from wherever you set it.

• Discord is the primary sign-in path.
• GitHub linking and GitHub contribution calendar rendering are implemented.
• itch.io linking exists and is token/client-ID based in the current implementation.
• Public profile links prefer linked provider URLs over manual URLs when available.
• OAuth-backed GitHub and itch.io links now render verified badges in the public profile UI.
• src/routes/demo/* still contains scaffold/demo routes and should not be treated as product truth.

The schema currently spans:

• auth
• user
• hammer
• collab
• public todos

Profile data still uses separate profile_projects and jam_participations tables. The unified typed-projects migration has not landed yet.

• bun run check runs Biome across the repo.
• bun run test uses Vitest.
• First-party automated coverage appears limited at the moment, so UI and route changes still need manual verification.

• Prefer reading the code over assuming the starter framework defaults still apply.
• Treat Notion as the longer-lived cross-session source of truth for architecture, drift, and planning context.
• Keep Linear issue status aligned with what actually shipped in the repo.

• The repo still needs a fuller setup/runbook for external services and credential provisioning.
• Demo routes remain in-tree.
• The route tree currently has at least one existing TypeScript issue outside normal profile work (src/routes/profile.$userId.tsx), so isolated validation is sometimes more useful than full repo typechecking.