Skip to main content
This guide will help you set up Raffi for local development.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Required

  • Node.js 18+ or Bun 1.0+
    • Download from nodejs.org or bun.sh
    • The desktop app uses Bun, but npm also works
  • Go 1.21+ (for the streaming server)
    • Download from go.dev
    • Required to build the server binary
  • Git

​
Optional

  • Expo CLI (for mobile development)
    • Install globally: npm install -g expo-cli
  • Xcode (for iOS development on macOS)
  • Android Studio (for Android development)

​
Clone the Repository

1

Clone the repository

git clone https://github.com/kaleidal/raffi.git
cd raffi
2

Verify directory structure

You should see the following directories:
raffi/
├── raffi-desktop/     # Desktop app (Electron + Svelte 5)
├── raffi-mobile/      # Mobile app (React Native + Expo)
├── raffi-server/      # Streaming server (Go)
├── raffi-site/        # Marketing website (SvelteKit)
└── convex/            # Backend functions (Convex)

​
Desktop App Setup

The desktop app is built with Electron and Svelte 5.
1

Navigate to desktop directory

cd raffi-desktop
2

Install dependencies

bun install
3

Start development server

This command builds the server binary and starts Electron in development mode:
bun run electron:dev
The app will open automatically once the Vite dev server is ready.

​
Desktop Development Commands

# Run in development mode (builds server + starts electron)
bun run electron:dev

# Run electron only (if server already built)
bun run electron:dev:only

# Build the streaming server binary
bun run server:build

# Build for production
bun run build

# Build and package for distribution
bun run dist

# Build for specific platform
bun run dist -- --win      # Windows
bun run dist -- --mac      # macOS
bun run dist -- --linux    # Linux
Built packages will be in raffi-desktop/release/.

​
Mobile App Setup

The mobile app is built with React Native and Expo SDK 54.
1

Navigate to mobile directory

cd raffi-mobile
2

Install dependencies

npm install
3

Configure streaming server

The mobile app requires the desktop server running for torrent streams.Update STREAMING_SERVER in app/player.tsx with your local IP address:
const STREAMING_SERVER = 'http://192.168.1.100:8080'; // Your local IP
4

Start Expo development server

npm start
This opens the Expo developer tools in your browser.

​
Mobile Development Commands

# Start Expo development server
npm start

# Run on iOS simulator (macOS only)
npm run ios

# Run on Android emulator
npm run android

# Run on web
npm run web

# Development builds
npx expo run:ios       # iOS
npx expo run:android   # Android

# Production builds (requires EAS account)
eas build --platform ios
eas build --platform android
Production builds use Expo Application Services (EAS). You’ll need an Expo account to build for production.

​
Streaming Server Setup

The streaming server is typically built automatically by the desktop app, but you can build and run it standalone.
1

Navigate to server directory

cd raffi-server
2

Build the server binary

go build -o decoder .
This creates a decoder binary in the current directory.
3

Run the server

./decoder
The server starts on port 8080 by default.
The desktop app’s electron:dev command automatically builds the server binary, so you typically don’t need to build it manually.

​
Marketing Website Setup

The marketing website is built with SvelteKit.
1

Navigate to site directory

cd raffi-site
2

Install dependencies

npm install
3

Start development server

npm run dev
The site will be available at http://localhost:5173.

​
Website Development Commands

# Run development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

​
Convex Backend Setup

Convex provides real-time backend functions for watch parties and synchronization.
1

Navigate to convex directory

cd convex
2

Install Convex CLI

bun add -g convex
3

Initialize Convex (if needed)

npx convex dev
This starts the Convex development server and watches for changes.

​
Troubleshooting

​
Desktop App Won’t Start

  • Ensure the server binary is built: bun run server:build
  • Check that ports 5173 and 8080 are available
  • Try running bun run electron:dev:only if the server is already built

​
Mobile App Can’t Connect to Server

  • Verify your local IP address in app/player.tsx
  • Ensure the desktop server is running
  • Check that your phone and computer are on the same network
  • Disable any firewalls blocking port 8080

​
Go Build Fails

  • Ensure Go 1.21+ is installed: go version
  • Update Go modules: go mod download
  • Check that your Go environment is properly configured

​
Expo Build Errors

  • Clear Expo cache: expo start -c
  • Reinstall dependencies: rm -rf node_modules && npm install
  • Update Expo CLI: npm install -g expo-cli@latest

​
Next Steps

Now that you have Raffi running locally, explore the project structure:

Project Structure

Learn about the codebase organization and key directories

Build docs developers (and LLMs) love

Get started for freeTalk to us