Skip to content

Development Setup

Jump to bottom
HlexNC edited this page Feb 25, 2026 · 2 revisions

Development Setup Guide

Complete guide for running and debugging the Zelara mobile app in different environments.

Table of Contents

  1. Prerequisites
  2. Quick Start
  3. Development Workflows
  4. Understanding Metro Bundler
  5. Troubleshooting
  6. Build Configurations

Prerequisites

Required Software

  • Node.js: >= 18.x
  • npm or yarn
  • JDK: 17 (configured in build.gradle:108-110)
  • Android Studio: Latest stable version
  • Android SDK: API 35 (compileSdk), API 34 (targetSdk), API 24+ (minSdk)
  • Android NDK: 27.2.12479018

Environment Setup

  1. Install dependencies:

    cd apps/mobile
npm install

  2. Verify Android environment:

    # Check ANDROID_HOME is set
echo $ANDROID_HOME  # Linux/Mac
echo $env:ANDROID_HOME # Windows

# Verify SDK installation
adb --version

  3. Connect device or start emulator:

    # List connected devices
adb devices

# Or start Android Studio AVD Manager and launch an emulator

Quick Start

Option A: VS Code (Recommended for beginners)

cd apps/mobile
npm run android

This automatically:

  1. Starts Metro bundler
  2. Builds debug APK
  3. Installs APK on device/emulator
  4. Runs the app

Option B: Android Studio (Current workflow)

IMPORTANT: When using Android Studio, Metro does NOT start automatically.

Step 1: Start Metro manually

cd apps/mobile
npm run start

Step 2: Run app in Android Studio

  • Click Run (▶️) button
  • Or: Run > Run 'app'
  • Or: Shift + F10

Development Workflows

VS Code + Metro CLI

Best for: Terminal-first developers, CI/CD scripts, automated testing

Standard Workflow

  1. Start Metro + Build + Run (all-in-one):

    cd apps/mobile
npm run android

  2. Alternative: Separate Metro server (more control):

    # Terminal 1: Start Metro
cd apps/mobile
npm run start

# Terminal 2: Build and run
npm run android

Debugging in VS Code

  1. Install React Native Tools extension:

    • Extension ID: msjsdiag.vscode-react-native

  2. Add .vscode/launch.json configuration:

    {
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Android",
      "cwd": "${workspaceFolder}/apps/mobile",
      "type": "reactnative",
      "request": "launch",
      "platform": "android"
    }
  ]
}

  3. Start debugging:

    • Press F5 or Run > Start Debugging
    • Set breakpoints in TypeScript/JavaScript files
    • Use Debug Console for evaluation

Hot Reload

  • Fast Refresh: Enabled by default - saves automatically reload
  • Manual reload: Shake device or press R twice in Metro terminal
  • Dev menu: Shake device or Cmd+M (Mac) / Ctrl+M (Windows/Linux)

Android Studio + Metro

Best for: Native module development, UI inspection, Android-specific debugging

📖 Detailed Build Setup: See Android-Studio-Build-Setup.md for:

  • Initial build configuration and troubleshooting
  • Automating Metro bundler in run configuration
  • Fixing Kotlin compilation errors
  • Build verification and testing

Critical Understanding: Why Metro Doesn't Auto-Start

Android Studio is an Android native IDE - it only handles:

  • Gradle builds
  • Native code compilation (Kotlin/Java)
  • APK packaging and installation

It does NOT:

  • Start JavaScript Metro bundler
  • Bundle JS code in debug builds (by design: build.gradle:64)

The Two-Step Workflow

Step 1: Start Metro Bundler

In VS Code integrated terminal or external terminal:

cd apps/mobile
npm run start

You should see:

                     ######                ######
                 ###     ####          ####     ###
                ##          ###      ###          ##
                ##             ##  ##             ##
                ##             ##  ##             ##
                ##           ##      ##           ##
                ##         ###          ###         ##
                 ##  ####                  ####  ##
                  #######                    ########

               Welcome to Metro v0.76.6
              Fast - Scalable - Integrated

 BUNDLER  Metro is now listening on port 8081

Keep this terminal open while developing.

Step 2: Build & Run in Android Studio

  1. Open apps/mobile/android/ in Android Studio
  2. Wait for Gradle sync to complete
  3. Select device/emulator from dropdown
  4. Click Run (▶️) or press Shift + F10

What happens:

  • Android Studio builds APK without bundled JS (debug mode)
  • APK is installed on device
  • App launches and connects to Metro at localhost:8081
  • Metro serves JavaScript bundle to the app

Port Forwarding (USB Debugging) - REQUIRED

IMPORTANT: When connecting phone via USB, you MUST run this command every time:

# Forward port 8081 from device to computer
adb reverse tcp:8081 tcp:8081

Why: USB-connected Android devices don't automatically forward localhost ports. Without this command:

  • Metro runs on computer at localhost:8081
  • Device tries to connect to localhost:8081 on itself (not computer)
  • Result: "Unable to load script" error

When to run:

  • ✅ Every time you connect phone via USB
  • ✅ After unplugging and re-plugging USB cable
  • ✅ After restarting adb (adb kill-server / adb start-server)
  • ✅ If you see "Metro server not found" errors

Verify it's working:

# Should show the port forwarding
adb reverse --list
# Expected output:
# tcp:8081 tcp:8081

Alternative - Skip Port Forwarding (Wireless Metro):

If you don't want to run adb reverse every time:

  1. Find your computer's IP address:

    # Windows
ipconfig
# Look for "Wireless LAN adapter Wi-Fi" → "IPv4 Address"

# Mac/Linux
ifconfig | grep inet

  2. In the mobile app:

    • Shake device to open Dev Menu
    • Settings → Debug server host & port
    • Enter: 192.168.x.x:8081 (your computer's IP)
    • Reload app

  3. Requirement: Phone and computer must be on same WiFi network

For wireless debugging, ensure device and computer are on same network.

Debugging with Android Studio

Native Code (Kotlin/Java):

  • Set breakpoints in .kt or .java files
  • Use Android Studio debugger (works normally)

JavaScript/React Code:

  1. Ensure Metro is running
  2. In app, open Dev Menu: Shake device or Cmd+M / Ctrl+M
  3. Select "Open Debugger" → Opens Chrome DevTools or React Native DevTools
  4. Set breakpoints in Sources tab

Logcat for Crash Logs:

  • View → Tool Windows → Logcat
  • Filter by package: ai.zelara.mobile
  • Look for ReactNativeJS tag for JS errors

Hot Reload in Android Studio

Works the same as CLI workflow:

  • Fast Refresh: Auto-reloads on save
  • Manual reload: R key twice in Metro terminal
  • Clear cache and reload: Dev Menu → Reload

Understanding Metro Bundler

What is Metro?

Metro is React Native's JavaScript bundler that:

  • Transforms TypeScript/JSX → JavaScript
  • Bundles all JS modules into single file
  • Serves bundle to app via HTTP (development)
  • Provides Fast Refresh (hot reload)

Metro vs Gradle

Component Role When It Runs
Metro Bundles JavaScript code npm run start or npm run android
Gradle Builds Android native code Android Studio build or npm run android

Debug vs Release Builds

Debug Build (build.gradle:64):

  • bundleInDebug: false - JS NOT bundled into APK
  • App expects Metro server at localhost:8081
  • Fast Refresh enabled
  • Not optimized, includes dev tools

Release Build (build.gradle:65):

  • bundleInRelease: true - JS bundled into APK
  • Standalone APK, no Metro needed
  • Minified, optimized, production-ready

Troubleshooting

Error: "Unable to load script. Make sure you're either running Metro..."

Screenshot Reference: Your error message from 14:02:42

Cause: APK built without bundled JS, but Metro server not running.

Solution:

# Start Metro in separate terminal
cd apps/mobile
npm run start

Then reload app:

  • Shake device → Reload
  • Or close and reopen app

Error: "Unable to instantiate application"

ClassNotFoundException: Didn't find class "ai.zelara.mobile.MainApplication"

Cause: Build cache corruption or Gradle sync issue.

Solution:

cd apps/mobile/android
./gradlew clean
./gradlew assembleDebug

# Then rebuild in Android Studio

Error: "dlopen failed: library 'libreact_featureflagsjni.so' not found"

Cause: Native libraries not properly linked (New Architecture issue).

Solution:

  1. Clean build:

    cd apps/mobile/android
./gradlew clean
rm -rf .gradle
rm -rf app/build

  2. Rebuild dependencies:

    cd apps/mobile
rm -rf node_modules
npm install

  3. Verify New Architecture is enabled: Check gradle.properties:35:

    newArchEnabled=true

  4. Rebuild:

    cd apps/mobile
npm run android

Metro Port 8081 Already in Use

Error: EADDRINUSE: address already in use :::8081

Solution:

Find and kill process:

# Linux/Mac
lsof -i :8081
kill -9 <PID>

# Windows
netstat -ano | findstr :8081
taskkill /PID <PID> /F

Or use different port:

npm run start -- --port 8082

Then update port forwarding:

adb reverse tcp:8082 tcp:8082

App Crashes Immediately After Install

Check Logcat:

  1. Android Studio → Logcat
  2. Filter: package:ai.zelara.mobile
  3. Look for FATAL EXCEPTION or ReactNativeJS errors

Common causes:

  • Missing native dependencies
  • Incorrect package name
  • Permissions not granted (camera, storage)

Solution:

# Check permissions in AndroidManifest.xml
cat android/app/src/main/AndroidManifestTest.xml

# Reinstall clean build
npm run android -- --reset-cache

Fast Refresh Not Working

Symptoms: Code changes don't appear in app

Solution:

  1. Verify Metro is running and shows bundling output
  2. Check Fast Refresh is enabled:
    • Dev Menu → Settings → Ensure "Fast Refresh" toggled ON
  3. Force reload:
    • Press R twice in Metro terminal
    • Or Dev Menu → Reload
  4. Clear Metro cache: 
    npm run start -- --reset-cache

Wireless Debugging Connection Issues

Problem: App can't reach Metro server on computer

Solution:

  1. Ensure same network:

    • Both device and computer on same WiFi
    • No VPN blocking local network

  2. Use computer's IP address:

    • Dev Menu → Settings → Debug server host
    • Enter: 192.168.x.x:8081 (your computer's IP)

  3. Check firewall:

    • Allow incoming connections on port 8081

Device Pairing Connection Issues

Error: "Failed to connect to Desktop" when scanning QR code

This is for Zelara Desktop ↔ Mobile device linking (port 8765), NOT Metro bundler (port 8081).

Checklist:

  1. Desktop WebSocket server running:

    # Check if port 8765 is listening
netstat -an | findstr :8765
# Expected: TCP    [IP]:8765    LISTENING
    • If not listening: Open Zelara Desktop app → Click "Generate QR Code"

  2. Windows Firewall rule created:

    # Run as Administrator
cd C:\Users\[YourUsername]\Documents\core\apps\desktop\scripts
.\setup-firewall.ps1
    • This allows inbound connections on port 8765

  3. Both devices on same WiFi network:

    # On Desktop (Windows)
ipconfig
# Note "Wireless LAN adapter Wi-Fi" → IPv4 Address (e.g., 172.25.99.241)
    • Mobile WiFi settings: Check connected network name
    • Must match Desktop's network (same SSID)
    • Mobile IP should be in same subnet (e.g., 172.25.x.x)

  4. Guest network / AP isolation:

    • Some routers isolate devices on guest networks
    • Try connecting to main WiFi network instead
    • Or use Mobile Hotspot workaround (see below)

Quick Test - Mobile Hotspot:

If unable to get both on same network:

  1. Mobile: Enable Personal Hotspot
  2. Desktop: Connect to Mobile's hotspot WiFi
  3. Desktop: Open Zelara → Generate new QR code (new IP from hotspot)
  4. Mobile: Scan QR code → Should work!

Detailed Troubleshooting: See Desktop DEVICE-PAIRING-TROUBLESHOOTING.md

Build Configurations

Understanding build.gradle

React Native Configuration Block (Lines 62-67)

project.ext.react = [
    enableHermes: true,      // Use Hermes JS engine
    bundleInDebug: false,    // Don't bundle JS in debug APK
    bundleInRelease: true,   // Bundle JS in release APK
    devDisabledInRelease: true
]

When to change bundleInDebug:

  • Keep false (default): Normal development with Hot Reload
  • Set true: Testing APK without Metro server (not recommended for dev)

Build Variants

Debug:

  • Fast build time
  • Metro-dependent
  • Development features enabled
  • APK: app-debug.apk

Release:

  • Optimized, minified
  • Standalone (Metro not needed)
  • ProGuard/R8 enabled
  • Requires signing configuration
  • APK: app-release.apk

Manual Bundle Creation

If you need to bundle JS manually (for testing release builds):

cd apps/mobile
npm run bundle:android

This creates:

  • android/app/src/main/assets/index.android.bundle
  • android/app/src/main/res/ (assets)

Then build release APK:

cd android
./gradlew assembleRelease

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

Best Practices

Development Workflow Checklist

  • Always start Metro before running app in Android Studio
  • Keep Metro terminal visible to see bundling logs
  • Use Fast Refresh instead of full rebuild for JS changes
  • Clean build when switching between branches
  • Use adb reverse for USB debugging
  • Check Logcat for crash details

Performance Tips

  • Use debug builds for development - Faster iteration
  • Clear Metro cache if seeing stale code: npm run start -- --reset-cache
  • Clean Gradle cache if build fails: cd android && ./gradlew clean
  • Reduce emulator resources if computer is slow (lower RAM/CPU allocation)

Team Collaboration

When sharing setup issues:

  1. Share Metro terminal output (bundling logs)
  2. Share Logcat filtered for ai.zelara.mobile
  3. Include adb devices output
  4. Mention which workflow you're using (VS Code CLI or Android Studio)

Additional Resources

Last Updated: 2025-02-24 React Native Version: 0.76.6 Target Android SDK: 35 (compileSdk), 34 (targetSdk)

Clone this wiki locally