Development Guide

🛠️ Prerequisites

Before starting, ensure you have the following installed:

Docker & Docker Compose (for database and containerized development)
Bun 1.0+ (JavaScript runtime)

🚀 Quick Setup

Bootstrap Project (Recommended)

The fastest way to get started:

git clone git@github.com:praveenjuge/teak.git
cd teak
bun run bootstrap

This single command will:

Install all dependencies across workspaces
Setup and configure the database
Initialize environment files
Verify prerequisites

Manual Setup (Alternative)

If you prefer step-by-step setup:

# Install all dependencies
bun run install:all

# Setup database (starts Docker containers, runs migrations, seeds data)
bun run setup:db

# Copy environment file
cp .env.example .env

🏗️ Project Architecture

Teak is a monorepo with the following structure:

Runtime: Bun
Backend: Hono.js API server (@teak/backend)
Web App: React 19 + Vite (@teak/web)
Mobile App: React Native with Expo (@teak/mobile)
Database: PostgreSQL 17 with Drizzle ORM
Containerization: Docker

🔧 Development Commands

Starting Services

# Start full development environment (Docker + all services)
bun run dev

# Start individual services
bun run dev:backend    # Backend API server only
bun run dev:frontend   # React web app only
bun run dev:mobile     # React Native mobile app

Building Applications

# Build all applications
bun run build

# Build individual apps
bun run build:backend
bun run build:frontend

🗄️ Database Development

Basic Commands

# Navigate to backend directory first
cd backend

bun run db:generate    # Generate database migrations
bun run db:migrate     # Apply migrations to database
bun run db:push        # Push schema changes directly
bun run db:studio      # Open Drizzle Studio (database GUI)
bun run db:seed        # Seed database with sample data

Root Level Database Utilities

bun run db:connect     # Connect to database via psql
bun run db:status      # Check database connection status
bun run db:reset       # Reset database (destructive!)

Database Connection Details

Development Database:

Host: localhost
Port: 5432
Database: teak_db
User: teak_user
Password: teak_dev_password

🐳 Docker Commands

Development Environment

bun run docker:dev         # Start development containers
bun run docker:dev:down    # Stop development containers
bun run docker:dev:clean   # Stop and remove all containers + volumes

Production Environment

bun run docker:prod        # Start production containers

Manual Docker Commands

# Navigate to docker directory
cd docker

# Start services
docker-compose up

# Start in background
docker-compose up -d

# Rebuild and start
docker-compose up --build

# Stop services
docker-compose down

# View logs
docker-compose logs -f

🌐 Development Services

Once your development environment is running, you can access:

Frontend: http://localhost:3000 (React 19 + Vite)
Backend API: http://localhost:3001 (Hono.js)
Database: localhost:5432 (PostgreSQL 17)
Drizzle Studio: http://localhost:4983 (when running db:studio)

⚙️ Environment Configuration

Required Environment Variables

Create a .env file from the template:

cp .env.example .env

Key Development Variables

Variable	Default	Description
`POSTGRES_DB`	`teak_db`	PostgreSQL database name
`POSTGRES_USER`	`teak_user`	PostgreSQL username
`POSTGRES_PASSWORD`	`teak_dev_password`	PostgreSQL password

Authentication Variables

Variable	Default	Description
`BETTER_AUTH_SECRET`	(required)	Secret key for Better Auth (min 32 chars)
`BETTER_AUTH_URL`	`http://localhost:3000`	Base URL for authentication callbacks
`ALLOW_MULTI_USER_REGISTRATION`	`false`	Allow multiple users to register

🚦 Development Workflow

Setup: Run bun run bootstrap to initialize the project
Start: Use bun run dev to start all services
Code: Make your changes to the appropriate workspace
Test: Verify your changes work in the development environment
Database: Use bun run db:studio to inspect database changes
Build: Run bun run build to ensure everything compiles

Development Guide

On this page