Prerequisites
System Requirements
- macOS, Windows, or Linux
- Node.js 18+ and npm
- Java Development Kit (JDK) 17+
- Android Studio (latest stable version)
- Android SDK Platform 34+
- Android SDK Build-Tools
Quick Start with Rock
New Expensify uses Rock to download pre-built native artifacts, avoiding lengthy Gradle builds.
Running the App
How Rock Works
- Fingerprint Generation: Creates fingerprint from native dependencies
- Remote Check: Looks for matching build on S3
- Download or Build: Downloads if available, builds locally if not
- Fast Iteration: Only rebuilds when native code changes
package.jsonandroid/build.gradleandroid/app/build.gradle- Native module changes
Manual Build Setup
1. Configure MapBox
2. React Native Environment
Follow the official React Native Android setup guide to install:- Android Studio
- Android SDK
- Android SDK Platform
- Android Virtual Device (AVD)
3. Optional: ccache Setup
Speed up C/C++ compilation with ccache:The build system automatically detects and uses ccache when available. No configuration needed!
4. Run the App
Android-Specific Features
Camera Receipt Scanning
Android camera integration with runtime permissions:src/components/AttachmentPicker/launchCamera/launchCamera.android.ts
Share Intent Handling
Android share intents for receipts and files:android/app/src/main/java/com/expensify/chat/MainActivity.kt
Push Notifications
Android uses FCM through Airship:android/app/src/main/java/com/expensify/chat/customairshipextender/CustomAirshipExtender.java
See Push Notifications for configuration details.
Background Tasks
Android background processing for sync and notifications:android/app/src/main/java/com/expensify/chat/customairshipextender/GpsTripService.kt
Hardware Back Button
Custom back button handling:Hardware Keyboard Shortcuts
android/app/src/main/java/com/expensify/chat/MainActivity.kt
Running on Physical Device
Enable USB Debugging
- Open Settings > About Phone
- Tap “Build Number” 7 times to enable Developer Options
- Go to Settings > Developer Options
- Enable “USB Debugging”
- Connect device via USB
Run App
Development Workflow
Hot Reload
JavaScript changes automatically reload:- Fast Refresh: Automatic for most changes
- Manual Reload: Double-tap R or shake device
- Debug Menu: Shake device or
Cmd + M(macOS) /Ctrl + M(Windows/Linux)
Debugging
- Chrome DevTools
- React DevTools
- Android Studio
New Expensify uses Hermes JS engine:
- Navigate to
chrome://inspect - Click “Configure” and add Metro server:
localhost:8081 - Find “Hermes React Native” target
- Click “inspect” to open DevTools
Testing Web in Android Emulator
To test the web app in Chrome on Android emulator:Performance Profiling
Enable Source Maps
Inandroid/app/build.gradle:
android/app/build.gradle
Record Performance Traces
- Build app in production mode
- Navigate to feature to profile
- Four-finger tap to open menu
- Select “Use Profiling”
- Interact with app
- Four-finger tap to stop
- Share trace file
Symbolicate Traces
Prebuilt React Native Artifacts
Speed up builds by using prebuilt React Native:Enable Prebuilt Artifacts
Editandroid/gradle.properties (Standalone) or Mobile-Expensify/Android/gradle.properties (HybridApp):
Configure GitHub CLI
Push Notification Setup (Development)
To receive push notifications while testing:HybridApp
EditMobile-Expensify/Android/assets/airshipconfig.properties:
Standalone
Copy production config to development:Troubleshooting
Rock Build Issues
Unexpected full build
Unexpected full build
- Reinstall dependencies:
- Run again:
Build still failing
Build still failing
- Clean Android directory:
- Try running again
Fingerprint mismatch
Fingerprint mismatch
- Check GitHub Actions: Android Builds
-
Compare fingerprints:
Gradle Issues
Metro Bundler Issues
ADB Connection Issues
Emulator Performance
Enable Hardware Acceleration
In Android Studio:
Tools > AVD Manager > Edit Device > Show Advanced SettingsSet:
- Graphics: Hardware - GLES 2.0
- Boot option: Cold boot
Certificate Installation Fails
If you see “adbd cannot run as root in production builds”:Native Modules
Creating Native Android Modules
android/app/src/main/java/com/expensify/chat/CustomModule.kt
Register Module
android/app/src/main/java/com/expensify/chat/CustomPackage.kt
Build Configurations
Debug vs Release
Build Variants
- debug: Development with debugging enabled
- release: Production-ready optimized build
- development: Hybrid development variant
Resources
React Native Docs
Official React Native Android setup
Android Developers
Android development resources
Rock Documentation
Learn about Rock build system
Airship Android SDK
Push notification integration
Next Steps
Receipt Scanning
Mobile receipt capture
Push Notifications
Configure push notifications
Offline Mode
Offline functionality
iOS Platform
iOS development setup
