Getting started

Prerequisites

Bun 1.3.0 (see root package.json engines and packageManager)
Git
Docker — optional but useful when mirroring production builds (see apps/client / apps/server Dockerfiles)
Access to the Surplus GitHub org if you are contributing in-house

Clone and install

git clone git@github.com:sharingexcess/surplus.git
cd surplus
bun install

Run the stack

The repo root exposes:

bun run dev

which uses Railway CLI (railway dev) to mirror how services are wired in hosted environments. Follow your team’s Railway project link and secrets setup.

For a minimal local loop without Railway, run the client and server the way each app documents (typically client on port 3000 and API on 8080—see apps/client and apps/server scripts and docs/architecture.md).

Environment

Client — build-time VITE_* variables (see apps/client/src/env.ts). For local dev on localhost, the client targets http://localhost:8080 for the API automatically.
Server — runtime env validated in apps/server/src/helpers/env.ts (never read env from packages/* libraries themselves).

Lint and types

Lint / format: bun run lint at the repo root (Biome).
Typecheck all workspaces: bun run typecheck (uses bun --filter='@surplus/*').
Docs app only: cd apps/docs && bun run typecheck

Where to read next

Monorepo layout
Architecture overview
Repository docs/architecture.md for full detail