Local setup

Prerequisites

• Bun 1.3.14 — the package manager and the API runtime. bun.lock is the lockfile that gates every deploy build.
• Node 22 — next build, the migration scripts and CI all run under Node. Both are needed; they are not alternatives.
• Access to the .env files (ask the team — they are not in the repo).

First run

git clone [email protected]:TCGKL/tcgkl-web.git
cd tcgkl-web
bun install --frozen-lockfile

# Env files live once at the repo root. apps/web/.env* are gitignored symlinks:
ln -s ../../.env apps/web/.env
ln -s ../../.env.local apps/web/.env.local

bun run dev        # web on :3000
bun run dev:api    # API on :4000, in a second terminal

The web app runs without the API: when API_INTERNAL_URL is unset, the thin routes under apps/web/src/app/(main)/api/* serve tRPC and auth locally. Set API_INTERNAL_URL=http://localhost:4000 to exercise the split the way production runs it.

Which database am I pointed at?

There is no local Postgres. .env.local points at beta, .env at production. Scripts run by a bare bun run load .env.local.

Check the host before running a script

A seed or backfill script picks up .env.local silently. For production, pin the env file explicitly and read the DB host the script prints:

bunx env-cmd -f .env -- bun run apps/web/scripts/<script>.ts

DATABASE_URL is the pooled Neon endpoint (-pooler, with sslmode=require&channel_binding=require); postgres.js runs with prepare: false because of PgBouncer. Migrations use DATABASE_URL_DIRECT, the non-pooler endpoint, and the migrate script refuses a -pooler host.

Connection refused or CONNECT_TIMEOUT is almost always one of those two URLs being wrong — or a dev server that needs restarting.

Everyday commands

All of these work from the repo root:

Command	What it does
bun run dev	Next.js web app on :3000
bun run dev:api	Hono API on :4000
bun run lint	Biome check
bun run format:fix	Biome autofix
bun run typecheck	tsc in every workspace, in parallel
bun run test	Unit tests
bun run db:generate	Generate a migration from schema changes
bun run db:migrate / db:migrate:beta	Apply migrations
bun run dev:stripe	Forward Stripe webhooks to localhost

Web-only scripts live in apps/web/package.json — run them with bun run --cwd apps/web <script>.

Every task ends with lint and typecheck

bun run lint && bun run typecheck before you open a PR. CI runs the same two commands and gates both the merge and the image build.

The docs site itself

bun run --cwd apps/docs dev      # this site, on :4321
bun run --cwd apps/docs build    # static output in apps/docs/dist

Pages are Markdown under apps/docs/src/content/docs/. The sidebar is generated from the folder structure — add a file, it appears. Order inside a group comes from sidebar.order in the frontmatter.