Installation

Prerequisites

Before installing Rippler, make sure you have the following tools installed on your system.

Node.js & npm

Required Version: Node.js 18+ with npm 9+Check your current versions:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 9.0.0 or higher

Install Node.js:

Download from nodejs.org
Or use a version manager like nvm:

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 18
nvm install 18
nvm use 18

Git

Required for: Cloning the repositoryCheck if installed:

git --version

Install Git:

macOS: brew install git or download from git-scm.com
Linux: sudo apt-get install git (Ubuntu/Debian) or sudo yum install git (CentOS/RHEL)
Windows: Download from git-scm.com

Expo CLI

Not required for installation - Expo CLI is included as a project dependency.The app uses npx expo commands which automatically use the correct version from node_modules.

PostgreSQL (Optional)

Required for: Server-side data persistence (optional for client-only development)Check if installed:

psql --version

Install PostgreSQL:

macOS: brew install postgresql@15 then brew services start postgresql@15
Linux: sudo apt-get install postgresql postgresql-contrib
Windows: Download from postgresql.org

Create the database:

createdb rippler

You can skip PostgreSQL setup if you only want to run the mobile app. AsyncStorage handles all client-side persistence.

Platform-Specific Setup

Choose your development platform(s). You can set up multiple platforms on the same machine.

iOS (macOS only)
Android
Web

iOS Development Setup

Install Xcode

Download Xcode from the Mac App Store (15GB+, takes 30+ minutes).After installation, open Xcode and accept the license agreement.Install command line tools:

xcode-select --install

Install iOS Simulator

Open Xcode → Settings → PlatformsDownload the iOS simulator runtime for your target iOS version (iOS 17+ recommended).

Install CocoaPods

Required for iOS native dependencies:

sudo gem install cocoapods
pod --version  # Verify installation

Install Expo Go (Optional)

For testing on a physical iPhone:

Open the App Store on your iPhone
Search for “Expo Go”
Install the app

Expo Go is free and doesn’t require an Apple Developer account for development.

Verify iOS Setup

Test that the simulator works:

npx expo start
# Press 'i' to open iOS simulator

The simulator should launch and the app should load automatically.

Android Development Setup

Install Android Studio

Download Android Studio from developer.android.comDuring installation, make sure to install:

Android SDK
Android SDK Platform
Android Virtual Device (AVD)

Configure Android SDK

Open Android Studio → Settings → Appearance & Behavior → System Settings → Android SDKInstall the following:

SDK Platforms: Android 13 (API 33) or higher
SDK Tools: Android SDK Build-Tools, Android Emulator, Android SDK Platform-Tools

Note your SDK location (e.g., ~/Android/Sdk)

Set Environment Variables

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin

Reload your shell:

source ~/.zshrc  # or source ~/.bashrc

Verify:

echo $ANDROID_HOME
adb --version

Create Virtual Device

Open Android Studio → Device Manager → Create DeviceRecommended configuration:

Device: Pixel 7 Pro
System Image: Android 13 (API 33) - x86_64
AVD Name: Pixel_7_Pro_API_33

Start the emulator to verify it works.

Install Expo Go (Optional)

For testing on a physical Android device:

Open Google Play Store on your phone
Search for “Expo Go”
Install the app
Enable Developer Options on your phone (tap Build Number 7 times in Settings)

Verify Android Setup

Test that the emulator works:

npx expo start
# Press 'a' to open Android emulator

The emulator should launch and the app should install automatically.

Web Development Setup

No additional setup required! Web support works out of the box with your existing browser.

Rippler uses React Native Web to render the same components in a browser. Some native features (haptics, camera) won’t work on web.

Test Web Version

npx expo start
# Press 'w' to open in browser

The app opens at http://localhost:8081 by default.

Project Installation

Now that your development environment is ready, let’s install Rippler.

Clone the Repository

git clone <repository-url> rippler
cd rippler

Replace <repository-url> with your actual repository URL.

Install Dependencies

Install all npm packages:

npm install

This installs:

Expo SDK and React Native
React Navigation and UI libraries
TanStack Query for state management
Express server dependencies
TypeScript and development tools

Expected output:

added 1342 packages, and audited 1343 packages in 45s

Installation may take 2-5 minutes depending on your internet speed.

Configure Environment Variables

Create a .env file in the project root:

.env

# Database Configuration (optional)
DATABASE_URL="postgresql://user:password@localhost:5432/rippler"

# Server Configuration
PORT=5000

# Replit Configuration (only for Replit deployments)
# REPLIT_DEV_DOMAIN="your-domain.replit.dev"
# REPLIT_DOMAINS="domain1.replit.dev,domain2.replit.dev"

Never commit .env to version control. It’s already in .gitignore.

Configuration Details:

DATABASE_URL: PostgreSQL connection string (optional for client-only dev)
PORT: Express server port (defaults to 5000)
REPLIT_*: Only needed if deploying to Replit

Set Up Database (Optional)

If you want to use the PostgreSQL backend:

# Create database
createdb rippler

# Push schema using Drizzle Kit
npm run db:push

The schema is defined in shared/schema.ts:

shared/schema.ts

import { pgTable, text, varchar } from "drizzle-orm/pg-core";
import { sql } from "drizzle-orm";

export const users = pgTable("users", {
  id: varchar("id")
    .primaryKey()
    .default(sql`gen_random_uuid()`),
  username: text("username").notNull().unique(),
  password: text("password").notNull(),
});

Currently the database is only used for user management. Workout data is stored in AsyncStorage on the client.

Verify Installation

Check that TypeScript compiles without errors:

npm run check:types

Expected output:

✓ No TypeScript errors

Run the linter:

npm run lint

Expected output:

✓ No linting errors

Development Servers

Rippler has two separate processes: the Expo dev server (client) and Express server (backend).

Start the Expo Dev Server

Start the React Native app with hot reloading:

npm run expo:dev

This runs:

EXPO_PACKAGER_PROXY_URL=https://$REPLIT_DEV_DOMAIN \
REACT_NATIVE_PACKAGER_HOSTNAME=$REPLIT_DEV_DOMAIN \
EXPO_PUBLIC_DOMAIN=$REPLIT_DEV_DOMAIN:5000 \
npx expo start --localhost

What these environment variables do

EXPO_PACKAGER_PROXY_URL: Proxy for Metro bundler (Replit-specific)
REACT_NATIVE_PACKAGER_HOSTNAME: Metro hostname for mobile devices
EXPO_PUBLIC_DOMAIN: Backend API URL accessible from the app

These are primarily for Replit deployments. For local dev, --localhost is sufficient.

Dev server options:

Press i → Open iOS simulator
Press a → Open Android emulator
Press w → Open web browser
Press r → Reload app
Press m → Toggle menu
Press j → Open debugger

Start the Express Server (Optional)

In a separate terminal, start the backend:

npm run server:dev

This runs:

NODE_ENV=development tsx server/index.ts

The server includes:

Express API routes
CORS configuration for Expo
Static file serving for production builds
Request logging middleware

server/index.ts

const app = express();

setupCors(app);           // Enable CORS for mobile clients
setupBodyParsing(app);    // JSON and form parsing
setupRequestLogging(app); // Log all API requests

configureExpoAndLanding(app);  // Serve Expo manifests
const server = await registerRoutes(app);  // API routes

setupErrorHandler(app);   // Global error handling

server.listen({ port: 5000, host: "0.0.0.0" });

The server is optional for client development. The mobile app works entirely with AsyncStorage without a backend.

Project Configuration

Understanding the key configuration files:

{
  "name": "my-app",
  "main": "client/index.js",
  "version": "1.0.0",
  "scripts": {
    "expo:dev": "EXPO_PACKAGER_PROXY_URL=... npx expo start --localhost",
    "server:dev": "NODE_ENV=development tsx server/index.ts",
    "db:push": "drizzle-kit push",
    "lint": "npx expo lint",
    "check:types": "tsc --noEmit",
    "format": "prettier --write \"**/*.{js,ts,tsx,css,json}\""
  },
  "dependencies": {
    "expo": "^54.0.23",
    "react": "19.1.0",
    "react-native": "0.81.5",
    "@tanstack/react-query": "^5.90.7",
    "drizzle-orm": "^0.39.3"
  }
}

Key Features Explained

New Architecture Enabled

Rippler uses React Native’s new architecture:

app.json

{
  "expo": {
    "newArchEnabled": true
  }
}

Benefits:

Faster rendering with synchronous layout
Better interop between JS and native code
Improved type safety with TurboModules

This requires React Native 0.81.5+ (which Rippler uses).

React Compiler (Experimental)

Rippler enables the experimental React Compiler:

app.json

{
  "expo": {
    "experiments": {
      "reactCompiler": true
    }
  }
}

The React Compiler automatically memoizes components and values, eliminating the need for manual useMemo and useCallback in many cases.

Path Aliases

Import from anywhere with clean paths:

// Instead of:
import { Button } from "../../../components/Button";

// Use:
import { Button } from "@/components/Button";

Configured in tsconfig.json and babel.config.js.

Drizzle ORM

Type-safe database queries with Drizzle:

import { drizzle } from "drizzle-orm/node-postgres";
import { users } from "@shared/schema";

const db = drizzle(pool);

// Fully typed queries
const allUsers = await db.select().from(users);

Schema migrations with:

npm run db:push  # Push schema changes

Troubleshooting

npm install fails with peer dependency warnings

Peer dependency warnings are normal with React Native. As long as the install completes, you can ignore them.If install fails completely, try:

rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

Metro bundler can't resolve @/* imports

Clear Metro cache and restart:

npx expo start --clear

If that doesn’t work, check that babel.config.js has the module-resolver plugin configured correctly.

iOS simulator doesn't open

Make sure Xcode is fully installed and you’ve accepted the license:

sudo xcodebuild -license accept
xcode-select --install

Check available simulators:

xcrun simctl list devices

Android emulator shows 'Could not connect to development server'

The emulator can’t reach Metro. Try:

adb reverse tcp:8081 tcp:8081
adb reverse tcp:5000 tcp:5000

Or use tunnel mode:

npx expo start --tunnel

Database connection fails

Verify PostgreSQL is running:

# macOS
brew services list

# Linux
sudo systemctl status postgresql

Test connection:

psql -U postgres -c "SELECT version();"

Check your .env file has the correct DATABASE_URL.

Next Steps

Architecture Overview

Learn how Rippler is structured and how components interact

API Reference

Explore the storage APIs, hooks, and type definitions

Component Library

Browse all reusable UI components with examples

Development Scripts

Learn about available npm scripts and development workflow

Installation complete! You now have a fully configured Rippler development environment. Start the dev servers and begin building.

Get Started

Core Features

Architecture

Development

Prerequisites

Platform-Specific Setup

iOS Development Setup

Verify iOS Setup

Android Development Setup

Verify Android Setup

Web Development Setup

Test Web Version

Project Installation

Development Servers

Start the Expo Dev Server

Start the Express Server (Optional)

Project Configuration

Key Features Explained

Troubleshooting

Next Steps

Architecture Overview

API Reference

Component Library

Development Scripts

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Development

Documentation Index

​Prerequisites

​Platform-Specific Setup

​iOS Development Setup

​Verify iOS Setup

​Android Development Setup

​Verify Android Setup

​Web Development Setup

​Test Web Version

​Project Installation

​Development Servers

​Start the Expo Dev Server

​Start the Express Server (Optional)

​Project Configuration

​Key Features Explained

​Troubleshooting

​Next Steps

Architecture Overview

API Reference

Component Library

Development Scripts

Build docs developers (and LLMs) love

Prerequisites

Platform-Specific Setup

iOS Development Setup

Verify iOS Setup

Android Development Setup

Verify Android Setup

Web Development Setup

Test Web Version

Project Installation

Development Servers

Start the Expo Dev Server

Start the Express Server (Optional)

Project Configuration

Key Features Explained

Troubleshooting

Next Steps