Configuration

Prerequisites

• Bun >= 1.3
• Node.js >= 24 (for compatibility)
• Docker (for local PostgreSQL)
• Git

Installation

# Clone the repository
git clone <repo-url>
cd roxabi_boilerplate

# Install dependencies
bun install

Environment Variables

Copy the example file and configure:

cp .env.example .env

Required Variables

Branch Databases (Local Development)

Each git worktree gets its own isolated PostgreSQL database named roxabi_<issue_number> within the shared Docker container. This prevents schema conflicts when multiple worktrees run concurrent migrations.

Branch databases are created automatically by /implement during worktree setup, or manually:

cd apps/api

# Create a branch database (migrate + seed + update .env)
bun run db:branch:create

# Create with explicit issue number (non-interactive)
bun run db:branch:create --force 150

# Drop a branch database
bun run db:branch:drop

# List all branch databases and their worktree status
bun run db:branch:list

# Seed a fresh database with dev essentials
bun run db:seed

Seed credentials: dev@roxabi.local / password123 (1 user, 1 organization, RBAC roles seeded).

All scripts run from apps/api/ and use docker exec against the roxabi-postgres container. No local psql installation is required.

Database Scripts (Root-Level)

Root-level wrappers load .env automatically and delegate to apps/api/. No need to cd into apps/api or set DATABASE_URL manually.

Common workflow:

# Fresh start after cloning
bun db:up && bun db:migrate && bun db:seed

# Reset and re-seed during development
bun db:reset && bun db:seed

db:reset and db:seed refuse to run when NODE_ENV=production (enforced at both the bash dispatcher and TypeScript script level).

Optional Variables

Public Variables (exposed to client)

Claude Code Agent Teams

To enable agent teams, set in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent definitions are in .claude/agents/*.md. See the Agent Teams Guide for details.

Complete Environment Variable Reference

Environment files (.env, .env.local) are resolved from the monorepo root only. Do not place .env files in app directories.

Core

Database

Authentication

Rate Limiting & API Features

Scheduled Tasks

Deployment

Public (Client-Side)

Tooling

TypeScript Configuration

Root tsconfig.json provides base settings. Each app/package extends it:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

Biome Configuration

Linting and formatting configured in biome.json:

• 2-space indentation
• Single quotes
• No semicolons (ASI)
• 100 character line width

TurboRepo Configuration

Tasks defined in turbo.jsonc:

• dev - Run development servers
• build - Build all packages
• codegen - Generate routes and i18n files
• typecheck - Type checking
• lint - Run linter
• test - Run tests
• clean - Remove build artifacts and caches
• license:check - Scan dependency licenses for compliance

Environment Variables in Turbo

The root turbo.jsonc declares env arrays for variables that affect build output — changing these values invalidates the Turbo cache:

• codegen: API_URL, APP_URL, VITE_*
• build: API_URL, APP_URL, KV_*, REDIS_*, VITE_*
• test: CI, VITEST

Wildcard patterns (e.g. VITE_*) automatically match all env vars with that prefix — no manual update to turbo.jsonc needed when adding new vars with a known prefix. For new prefixes, add a wildcard pattern to the relevant task.

The API app extends the root config via apps/api/turbo.json with passThroughEnv for runtime secrets (database, auth). These are available at runtime but don't affect the build cache, preventing unnecessary rebuilds when only secrets change.

IDE Setup

VS Code

Recommended extensions:

• Biome
• TypeScript
• Turbo Console Log

Settings:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

Production Environment

Production runs entirely on Vercel with two projects (web + API). Environment variables are configured in each project's dashboard.

Vercel — Web Project

Configure in Vercel dashboard under Settings > Environment Variables:

Vercel — API Project

Configure in Vercel dashboard under Settings > Environment Variables (manual vars) or via Marketplace Integrations (auto-injected vars):

Auto-injected vars are managed by their respective Vercel Marketplace integrations and do not need manual configuration. They appear with an integration badge in the Vercel dashboard. For local development, these vars still need to be set manually in .env.

Note: Vercel auto-sets NODE_ENV=production. NestJS runs as a Vercel Function with Fluid compute.

See the Deployment Guide for full setup instructions.