Building from Source

This guide covers building Off Grid from source, including prerequisites, setup, and platform-specific build commands.

Prerequisites

Node.js 20+

Off Grid requires Node.js 20 or higher. Install from nodejs.org or use a version manager like nvm.

node --version  # Should be 20.x or higher

React Native CLI

Install the React Native CLI globally:

npm install -g react-native-cli

Platform-Specific Tools

Install the required tools for your target platform:

Android
iOS
macOS

JDK 17 - Java Development Kit (Temurin/Adoptium recommended)
Android SDK (API 36) - Install via Android Studio
Android NDK r27 - Required for native module compilation
Android Studio - Recommended for device emulation and debugging

Verify your setup:

java -version      # Should be 17.x
echo $ANDROID_HOME # Should point to Android SDK

Xcode 15+ with iOS 17 SDK - Download from Mac App Store
CocoaPods - iOS dependency manager
Apple Developer Account - Required for device deployment (free tier available)

Install CocoaPods:

sudo gem install cocoapods

Verify Xcode:

xcodebuild -version  # Should be 15.x or higher

Clone and Install

Clone the repository

git clone https://github.com/alichherawalla/off-grid-mobile.git
cd off-grid-mobile

Install JavaScript dependencies

npm install

This installs all React Native and JavaScript dependencies defined in package.json.

Platform setup

Android
iOS

cd android
./gradlew clean
cd ..

This cleans the Gradle build cache and prepares the Android project.

cd ios
pod install
cd ..

This installs native iOS dependencies (CocoaPods) including llama.rn, whisper.rn, and Core ML modules.

Development Builds

Start Metro Bundler

First, start the Metro bundler in a terminal:

npm start

Leave this running and open a new terminal for platform-specific commands.

Android

npm run android

react-native run-android --mode=debug --appId ai.offgridmobile.dev

This launches the app on a connected Android device or emulator.

Make sure you have a device connected via ADB or an emulator running before executing the build command.

iOS

npm run ios

react-native run-ios

# Alternative: Open in Xcode
open ios/OffgridMobile.xcworkspace
# Select target device → Build & Run (⌘R)

Always open OffgridMobile.xcworkspace, not OffgridMobile.xcodeproj. The workspace includes CocoaPods dependencies.

Release Builds

Android

Create keystore (first time only)

keytool -genkeypair -v -storetype PKCS12 -keystore my-release-key.keystore \
  -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Store the keystore file in a secure location (not in the repository).

Configure signing

Create or edit android/gradle.properties:

android/gradle.properties

MYAPP_RELEASE_STORE_FILE=my-release-key.keystore
MYAPP_RELEASE_KEY_ALIAS=my-key-alias
MYAPP_RELEASE_STORE_PASSWORD=your_keystore_password
MYAPP_RELEASE_KEY_PASSWORD=your_key_password

Never commit gradle.properties with credentials to version control. Add it to .gitignore.

Build the release APK

cd android
./gradlew assembleRelease

The signed APK will be at:

android/app/build/outputs/apk/release/app-release.apk

iOS

Open Xcode

open ios/OffgridMobile.xcworkspace

Archive the build

Select Product → Archive
Wait for the archive to complete
The Organizer window will open automatically

Distribute the app

Select your archive
Click Distribute App
Choose distribution method:
- App Store Connect - For App Store submission
- Ad Hoc - For TestFlight or direct distribution
- Development - For local testing
Follow the signing and provisioning workflow

Troubleshooting

Android Build Errors

Gradle build fails

Clear the Gradle cache and rebuild:

cd android
./gradlew clean
./gradlew assembleDebug --rerun-tasks

NDK not found

Install the NDK via Android Studio:

Open Tools → SDK Manager
Select SDK Tools tab
Check NDK (Side by side)
Click Apply to install

Multiple build tools versions

Edit android/build.gradle and ensure buildToolsVersion matches your installed version:

buildToolsVersion = "34.0.0"

iOS Build Errors

CocoaPods errors

Clean and reinstall pods:

cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

Signing errors

Open OffgridMobile.xcworkspace in Xcode
Select the project in the navigator
Go to Signing & Capabilities
Select your Team (requires Apple Developer account)
Xcode will automatically manage provisioning profiles

Build hangs on 'Installing' step

This usually means the device is locked. Unlock your device and try again.

Next Steps

Project Structure

Learn how the codebase is organized

Testing Guide

Run tests and understand the testing strategy

Contributing

Learn the contribution workflow and quality gates

​Prerequisites

​Clone and Install

​Development Builds

​Start Metro Bundler

​Android

​iOS

​Release Builds

​Android

​iOS

​Troubleshooting

​Android Build Errors

​iOS Build Errors

​Next Steps

Project Structure

Testing Guide

Contributing

Prerequisites

Clone and Install

Development Builds

Start Metro Bundler

Android

iOS

Release Builds

Android

iOS

Troubleshooting

Android Build Errors

iOS Build Errors

Next Steps