Running Locally

Prerequisites

Node.js 20+
pnpm 11+ — install with npm i -g pnpm
PostgreSQL 15+ — running and accessible
Expo Go on your phone, or an Android/iOS simulator

1. Install dependencies

From the monorepo root:

pnpm install

2. Set up environment variables

Copy the example file:

cp .env.example .env

Then edit .env. The required variables are:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string, e.g. `postgresql://user:pass@localhost:5432/musubi`
`BETTER_AUTH_SECRET`	Any long random string — used to sign sessions
`BETTER_AUTH_URL`	The origin of the API server, e.g. `http://localhost:3000`. No trailing slash, no `/api` suffix.
`API_SERVER_PORT`	Port the API listens on. Defaults to `3000`
`ENVIRONMENT`	Set to `dev` during development — enables CORS for localhost

SMTP variables (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, FROM_EMAIL) are only required if you want password reset emails to actually send. The app works without them in development.

3. Run database migrations

pnpm db:migrate

This applies all pending Drizzle migrations to your PostgreSQL database.

4. Start everything

From the monorepo root:

pnpm dev

Turborepo runs the API, the Expo client, and the docs site in parallel with an interactive TUI — each gets its own pane. Use --ui=stream for plain output.

To run a single piece in isolation:

cd apps/api && pnpm dev        # API only  → http://localhost:3000
cd apps/client && pnpm dev     # Expo client only
cd packages/docs && pnpm dev   # Docs site only → http://localhost:4321/docs

The Expo dev server will print a QR code. Scan it with Expo Go on your phone, or press i for an iOS simulator or a for Android.