Building and Running the App

Development Server

Start the Expo development server with the dev client:

pnpm start

This command starts the Metro bundler and opens the Expo DevTools. You can then:

Press i to open iOS simulator
Press a to open Android emulator
Scan the QR code with Expo Go app (development builds only)

The development server runs on the default Expo port. The app uses a custom dev client, so you’ll need to build it first (see below).

Running on iOS

iOS development requires a Mac with Xcode installed.

Development Build

Run the app on iOS simulator or connected device:

Start iOS simulator

Open Xcode and launch a simulator, or connect a physical iOS device.

Run the development build

pnpm ios

This command:

Builds the native iOS app
Installs it on the simulator/device
Starts the Metro bundler
Opens the app automatically

iOS Simulator Selection

To run on a specific simulator:

# List available simulators
xcrun simctl list devices

# Run on specific simulator
pnpm ios --simulator="iPhone 15 Pro"

iOS Device Configuration

The app is configured with:

Bundle Identifier: bz.medusa.wallet
Supports iPad: Yes
Orientation: Portrait only
Required Capabilities: Camera, Face ID

Check app.json for the complete iOS configuration:

"ios": {
  "supportsTablet": true,
  "bundleIdentifier": "bz.medusa.wallet"
}

Running on Android

Development Build

Run the app on Android emulator or connected device:

Start Android emulator

Launch an Android Virtual Device (AVD) from Android Studio, or connect a physical Android device with USB debugging enabled.

Run the development build

pnpm android

This command:

Builds the native Android app
Installs it on the emulator/device
Starts the Metro bundler on port 8082
Opens the app automatically

The Android script uses a custom port (8082) to avoid conflicts:

"android": "expo run:android --port 8082"

Android Device Configuration

The app is configured with:

Package Name: bz.medusa.wallet
Version Code: 3
Target SDK: Latest (via Expo)
Permissions: Camera
Status Bar: Light content on dark background

"android": {
  "package": "bz.medusa.wallet",
  "versionCode": 3,
  "permissions": ["android.permission.CAMERA"],
  "adaptiveIcon": {
    "backgroundColor": "#0A0A0A"
  }
}

Android Emulator Tips

Check connected devices

adb devices

You should see your emulator or device listed.

Reverse port for Metro bundler

If the app can’t connect to Metro:

adb reverse tcp:8082 tcp:8082

Clear app data

adb shell pm clear bz.medusa.wallet

View logs

# View all logs
adb logcat

# Filter React Native logs
adb logcat | grep ReactNative

Platform Differences

When developing for both platforms, be aware of these differences:

iOS
Android

iOS-Specific Features

Face ID: Configured with permission message
Haptics: Different feedback patterns
Status Bar: Managed by expo-status-bar
Safe Areas: Automatic handling for notches

iOS Configuration

// Platform-specific code
if (Platform.OS === 'ios') {
  // iOS-specific logic
}

Android-Specific Features

Navigation Bar: Custom color (#0A0A0A)
Status Bar: Custom styling
Adaptive Icon: Custom background color
System UI: Background color override

Android Configuration

// Platform-specific code
if (Platform.OS === 'android') {
  SystemUI.setBackgroundColorAsync(Colors.dark)
}

Development Tools

React Query DevTools

The app includes React Query DevTools for debugging:

Enable DevTools

DevTools are automatically enabled in development mode:

// app/_layout.tsx
import { useReactQueryDevTools } from '@dev-plugins/react-query'

const queryClient = new QueryClient()
useReactQueryDevTools(queryClient)

Access DevTools

Open the Expo DevTools and navigate to the React Query panel to:

View active queries
Inspect cache state
Debug refetch behavior
Monitor network requests

Learn more about React Query DevTools in the Expo documentation.

Metro Bundler

The Metro bundler provides useful commands during development:

Reload App

Press r in the terminal

Open DevTools

Press d in the terminal

Toggle Element Inspector

Press i in the terminal

Clear Cache

Press Shift + r in the terminal

Remote Debugging

Debug JavaScript in Chrome DevTools:

Shake your device (or press Cmd+D on iOS simulator / Cmd+M on Android emulator)
Select “Debug” from the menu
Chrome will open with DevTools

Remote debugging can cause performance issues. Use it only when necessary.

Code Quality

Ensure code quality before committing:

pnpm type-check

Pre-commit Workflow

Recommended workflow before committing:

# 1. Check types
pnpm type-check

# 2. Fix formatting
pnpm format:fix

# 3. Run linter
pnpm lint

# 4. Run tests
pnpm test

Production Builds

Production builds require EAS (Expo Application Services) configuration.

EAS Configuration

The app uses EAS for production builds:

// eas.json
{
  "build": {
    "development": {
      "developmentClient": true
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  }
}

Build Commands

iOS
Android

# Development build
eas build --profile development --platform ios

# Production build
eas build --profile production --platform ios

# Development build
eas build --profile development --platform android

# Production build
eas build --profile production --platform android

EAS builds run on Expo’s servers. You’ll need an Expo account to use EAS Build.

Testing

Running Tests

The app includes unit and integration tests:

pnpm test

Test Structure

tests/
├── unit/
│   └── utils/              # Utility function tests
│       ├── wallet.test.ts
│       ├── format.test.ts
│       └── validation.test.ts
└── int/
    └── api/                # API integration tests
        └── medusa.test.ts

Writing Tests

Example test file:

import { formatBitcoin } from '@/utils/format'

describe('formatBitcoin', () => {
  it('should format satoshis correctly', () => {
    expect(formatBitcoin(100000000)).toBe('1.00000000')
  })
})

Troubleshooting

Metro bundler not starting

Clear the Metro cache:

pnpm start --clear

Or manually:

rm -rf node_modules/.cache

Build fails on iOS

Clean the build folder:
```
cd ios
xcodebuild clean
cd ..
```

Reinstall CocoaPods:

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

Rebuild:
```
pnpm ios
```

Build fails on Android

Clean the Gradle cache:
```
cd android
./gradlew clean
cd ..
```
Rebuild:
```
pnpm android
```

App crashes on launch

Check the logs:iOS:

xcrun simctl spawn booted log stream --level debug

Android:

adb logcat

Hot reload not working

Ensure you’re connected to the same network
Restart Metro bundler
Reload the app (r in terminal)

Performance Optimization

Use FlashList

Replace FlatList with @shopify/flash-list for better performance

Optimize Images

Use expo-image for optimized image loading

Memoization

Use React.memo() and useMemo() for expensive computations

Code Splitting

Lazy load components with React.lazy() and Suspense

Next Steps

Architecture

Learn about the app architecture

Contributing

Contribute to Medusa Wallet

Developer Guide

API Reference

Components

​Development Server

​Running on iOS

​Development Build

​iOS Simulator Selection

​iOS Device Configuration

​Running on Android

​Development Build

​Android Device Configuration

​Android Emulator Tips

​Platform Differences

​iOS-Specific Features

​iOS Configuration

​Android-Specific Features

​Android Configuration

​Development Tools

​React Query DevTools

​Metro Bundler

Reload App

Open DevTools

Toggle Element Inspector

Clear Cache

​Remote Debugging

​Code Quality

​Pre-commit Workflow

​Production Builds

​EAS Configuration

​Build Commands

​Testing

​Running Tests

​Test Structure

​Writing Tests

​Troubleshooting

​Performance Optimization

Use FlashList

Optimize Images

Memoization

Code Splitting

​Next Steps

Architecture

Contributing

Build docs developers (and LLMs) love

Development Server

Running on iOS

Development Build

iOS Simulator Selection

iOS Device Configuration

Running on Android

Development Build

Android Device Configuration

Android Emulator Tips

Platform Differences

iOS-Specific Features

iOS Configuration

Android-Specific Features

Android Configuration

Development Tools

React Query DevTools

Metro Bundler

Remote Debugging

Code Quality

Pre-commit Workflow

Production Builds

EAS Configuration

Build Commands

Testing

Running Tests

Test Structure

Writing Tests

Troubleshooting

Performance Optimization

Next Steps