Quickstart

This page gets you from zero to a running local stack. It should take about ten minutes once you have access to the repository.

Prerequisites

• Bun 1.3.0 — the runtime, package manager, and test runner. Surplus pins this exact version in the root package.json (engines and packageManager). There is no separate Node.js or TypeScript build step; Bun runs .ts files directly.
• Git and access to the sharingexcess/surplus repository.
• Railway CLI (recommended) — local development injects environment variables and secrets through Railway, exactly the way hosted environments are wired. Install it with bun add -g @railway/cli or follow Railway's instructions.
• Docker (optional) — only needed if you want to reproduce production container builds locally.

Clone and install

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

bun install resolves the entire workspace — every app and package — in one pass.

Run the stack

From the repository root:

bun run dev

This runs railway dev, which starts the apps together with environment variables and secrets pulled live from Railway. When everything is up you'll have:

When you're done, bun run kill frees those three ports if anything is left running.

Why Railway for local dev? Surplus connects to managed services — PostgreSQL (Neon), Redis (Upstash), and S3-compatible storage (Tigris). Rather than asking every contributor to provision and configure those by hand, local dev borrows the same injected configuration the hosted environments use. This keeps "works on my machine" surprises to a minimum.

Running without Railway

Each app also has its own dev script, so you can run pieces individually:

# API server (port 8080) — hot reload, instrumentation preloaded
cd apps/server && bun run dev

# Web client (port 3000)
cd apps/client && bun run dev

# Docs site (port 4000)
cd apps/docs && bun run dev

Run this way, the apps still need their environment variables. The required variables are defined and validated in:

• Server — apps/server/src/helpers/env.ts (database, Redis, S3, JWT signing, Stripe, Resend, and more).
• Client — apps/client/src/env.ts (build-time VITE_* values; on localhost the client targets http://localhost:8080 automatically).

Packages never read environment variables directly — configuration is always injected at the app layer. See Conventions for why.

Verify your setup

Two commands confirm a healthy checkout:

# Type-check every workspace package
bun run typecheck

# Lint and auto-format with Biome
bun run lint

Both run from the repository root. typecheck fans out across all @surplus/* packages; lint uses Biome to check and fix formatting in one step.

Run the tests

End-to-end tests use Playwright against ephemeral infrastructure:

bun run test

This provisions a throwaway Neon database branch and Upstash Redis instance, runs the suite, and tears everything down afterward. The Testing page explains how it works and how to write new tests.

Where to go next

• Architecture overview — see how the pieces connect.
• The Stack — a tour of each app and package.
• Contributing — how to propose changes.