Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

​
Required Software

  • Node.js 20 or later - JavaScript runtime
  • Yarn 1.22.22 - Package manager (not npm)
  • Git - Version control

​
Platform-Specific Requirements

​
For Mobile Development (happy-app)

  • Expo CLI - Installed automatically with dependencies
  • iOS Development:
    • macOS with Xcode 15+
    • iOS Simulator or physical device
  • Android Development:
    • Android Studio
    • Android SDK and emulator

​
For Server Development (happy-server)

  • PostgreSQL - Database (can use Docker)
  • Redis - Cache and pub/sub (can use Docker)
  • FFmpeg - Media processing
  • Python 3 - Required by some dependencies
  • Docker (optional) - For running services locally

​
Installation Steps

1
Clone the repository
2
git clone https://github.com/slopus/happy.git
cd happy
3
Install dependencies
4
From the repository root, install all workspace dependencies:
5
yarn install
6
This will install dependencies for all packages in the monorepo.
7
Set up environment variables
8
For happy-cli
9
Create environment files for local development:
10
cd packages/happy-cli
cp .env.example .env.dev-local-server  # if example exists
11
Set HAPPY_SERVER_URL to your local server:
12
HAPPY_SERVER_URL=http://localhost:3005
HAPPY_HOME_DIR=~/.happy-dev
13
For happy-server
14
cd packages/happy-server
cp .env.example .env.dev  # if example exists
15
Configure your database and Redis connections in .env.dev.
16
Generate Prisma client
17
For the server package:
18
cd packages/happy-server
yarn generate
19
Run database migrations
20
Set up the database schema:
21
cd packages/happy-server
yarn migrate
22
Start local services (optional)
23
If using Docker for development services:
24
# PostgreSQL
cd packages/happy-server
yarn db

# Redis
yarn redis

# MinIO (S3-compatible storage)
yarn s3
yarn s3:init

​
Verify Installation

Test that everything is set up correctly:

​
Test CLI

yarn cli --help

​
Test Server

cd packages/happy-server
yarn dev
The server should start on http://localhost:3005.

​
Test Mobile App

cd packages/happy-app
yarn start
This starts the Expo development server. You can then:
  • Press i for iOS simulator
  • Press a for Android emulator
  • Press w for web browser

​
Development Variants

The CLI supports running development and stable versions side-by-side: 
# Development variant (uses ~/.happy-dev)
yarn dev:variant

# Stable variant (uses ~/.happy)
yarn stable

​
IDE Setup

The project includes VS Code workspace configurations in .vscode directories within each package. Install recommended extensions:
  • ESLint
  • TypeScript
  • Prettier (if used)

​
TypeScript

All packages use TypeScript 5.9.3 with strict mode enabled. Run type checking: 
# From any package directory
yarn typecheck

​
Troubleshooting

​
Port conflicts

If port 3005 is in use, the server dev script will attempt to kill the process: 
lsof -ti tcp:3005 | xargs kill -9

​
Prisma issues

Regenerate Prisma client: 
cd packages/happy-server
yarn generate
Reset database: 
yarn migrate:reset

​
Yarn workspace issues

If you encounter workspace-related errors, try: 
# From repository root
rm -rf node_modules
rm -rf packages/*/node_modules
yarn install

​
Happy CLI daemon issues

Run the doctor command: 
cd packages/happy-cli
yarn doctor

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us