Skip to main content

​
Get Started in 5 Minutes

This guide will get you from zero to running the Rippler app on your phone or simulator as quickly as possible. For a more detailed setup, see the Installation guide.
Prerequisites: You need Node.js 18+ and npm installed. Check with node --version and npm --version.

​
Quick Setup

1

Clone and Install

Clone the repository and install dependencies:
git clone <repository-url>
cd rippler
npm install
This will install all required packages including Expo, React Native, and dependencies.
2

Set Up Environment Variables

Create a .env file in the project root:
.env
DATABASE_URL="postgresql://user:password@localhost:5432/rippler"
REPLIT_DEV_DOMAIN="your-domain.replit.dev"  # Optional, for Replit deployments
If you don’t have PostgreSQL running locally, you can skip database setup for now. The app will still work with AsyncStorage for workout logging.
3

Start the Development Server

Run the Expo development server:
npm run expo:dev
This starts the Expo dev server with proper environment variables configured for React Native.
› Metro waiting on exp://192.168.1.100:8081
› Scan the QR code above with Expo Go (Android) or the Camera app (iOS)

› Press a │ open Android
› Press i │ open iOS simulator
› Press w │ open web
4

Open on Your Device

Choose how you want to run the app:
iOS:
  1. Install Expo Go from the App Store
  2. Open the Camera app
  3. Scan the QR code in your terminal
  4. Tap the notification to open in Expo Go
Android:
  1. Install Expo Go from the Play Store
  2. Open Expo Go
  3. Tap “Scan QR Code”
  4. Scan the QR code in your terminal
5

Explore the App

You should now see the Rippler home screen with the 12-week program!Try these actions:
  • Navigate to Program tab to see all 12 weeks
  • Tap any workout day to start logging
  • Open Goals tab to set your 1RM targets
  • Check History to see completed workouts

​
Understanding the App Structure

Once the app is running, here’s what you’ll see:
The Program tab shows your current week with all scheduled training days:
client/navigation/MainTabNavigator.tsx
<Tab.Screen
  name="ProgramTab"
  component={ProgramStackNavigator}
  options={{
    title: "Program",
    tabBarIcon: ({ color, size }) => (
      <Feather name="calendar" size={size} color={color} />
    ),
  }}
/>
  • Week selector at the top (swipe or tap arrows)
  • 4 workout cards per week (Tuesday, Thursday, Saturday, Sunday)
  • Tap any card to open the workout and start logging
The workout screen is where the magic happens:
client/screens/WorkoutScreen.tsx
// Initialize workout with targets from program
const initializeLoggedWorkout = useCallback((): LoggedWorkout => {
  return {
    id: `${week}-${day}`,
    week,
    day,
    dateLogged: new Date().toISOString(),
    exercises: targetWorkout.exercises.map((ex, index) => {
      const effective = getEffectiveTarget(ex, index);
      const totalSets = typeof effective.sets === "number"
        ? effective.sets
        : parseInt(String(effective.sets).replace("+", ""), 10);

      return {
        tier: ex.tier,
        exercise: ex.exercise,
        sets: Array.from({ length: totalSets }, (_, i) => ({
          setNumber: i + 1,
          weight: "",
          reps: "",
          completed: false,
        })),
      };
    }),
    completed: false,
  };
}, [week, day, targetWorkout, getEffectiveTarget]);
Features:
  • Expandable exercise cards with tier badges (T1, T2, T3)
  • Target weights/reps calculated from your 1RM goals
  • Set-by-set logging with weight and rep inputs
  • Progress bar showing overall completion
  • Edit button to modify targets on the fly
Set your training maxes for automatic weight calculations:
  • Enter 1RM for Bench, Squat, Deadlift, OHP
  • Weights automatically calculate for all exercises
  • Changes apply to all future workouts
  • Goals persist locally in AsyncStorage
View your complete training history:
  • Calendar view with completed workout indicators
  • Week-by-week progression
  • Tap any past workout to review sets/reps

​
Development Workflow

​
Hot Reloading

The app supports fast refresh. Make changes to any component and see them instantly:
client/components/Button.tsx
export function Button({ children, onPress, variant = "primary" }) {
  return (
    <Pressable
      onPress={onPress}
      style={({ pressed }) => [
        styles.button,
        variant === "primary" ? styles.primary : styles.secondary,
        pressed && styles.pressed,
      ]}
    >
      <ThemedText style={styles.buttonText}>{children}</ThemedText>
    </Pressable>
  );
}
Change the button style and it updates immediately on your device.

​
Testing on Multiple Platforms

Rippler runs on iOS, Android, and web from the same codebase: 
npm run expo:dev
# Then press 'i' in terminal

​
TypeScript Support

The app is fully typed with TypeScript. Hover over any component for type information:
client/types/workout.ts
export interface WorkoutDay {
  week: number;
  day: string;
  dateSerial: number;
  exercises: TargetExercise[];
}

export interface TargetExercise {
  tier: string;
  exercise: string;
  weight: number | string;
  reps: number | string;
  sets: number | string;
}

export interface LoggedSet {
  setNumber: number;
  weight: string;
  reps: string;
  completed: boolean;
}

​
Running the Backend (Optional)

If you want to test the full stack with database persistence:
1

Start PostgreSQL

Make sure PostgreSQL is running and create the database:
createdb rippler
2

Run Migrations

Push the database schema:
npm run db:push
3

Start the Server

Run the Express server in development mode:
npm run server:dev
The server starts on port 5000 by default.

​
Common Issues

This is a path alias issue. Make sure your babel.config.js is correct:
babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    plugins: [
      [
        "module-resolver",
        {
          root: ["./"],
          alias: {
            "@": "./client",
            "@shared": "./shared",
          },
        },
      ],
      "react-native-reanimated/plugin",
    ],
  };
};
Then restart the dev server with npm run expo:dev.
Make sure your phone and computer are on the same WiFi network.If that doesn’t work, try:
npx expo start --tunnel
This uses a cloud tunnel to connect.
If you see database errors, check your .env file:
# Make sure DATABASE_URL is correct
DATABASE_URL="postgresql://user:password@localhost:5432/rippler"
Or skip the database entirely - the app works with AsyncStorage only.
Make sure you have Android Studio installed and an emulator configured.List available emulators:
emulator -list-avds
Create one if needed through Android Studio > AVD Manager.

​
Next Steps

Full Installation Guide

Set up your complete development environment with all tools

Architecture Overview

Understand how Rippler is built and how the pieces fit together

Program Management

Learn how to manage and customize workout programs

API Reference

Explore the storage APIs, hooks, and type definitions
You’re all set! The app should be running and you can start exploring the codebase. Make changes and see them update in real-time with Fast Refresh.

Build docs developers (and LLMs) love

Get started for freeTalk to us