Skip to main content
New Expensify for Android provides a native experience with full offline support, camera receipt scanning, and Material Design integration.

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
Follow the React Native Environment Setup for detailed prerequisites.

Quick Start with Rock

New Expensify uses Rock to download pre-built native artifacts, avoiding lengthy Gradle builds.

Running the App

For standalone NewDot (without HybridApp integration), use npm run android-standalone.

How Rock Works

  1. Fingerprint Generation: Creates fingerprint from native dependencies
  2. Remote Check: Looks for matching build on S3
  3. Download or Build: Downloads if available, builds locally if not
  4. Fast Iteration: Only rebuilds when native code changes
Files that trigger rebuild:
  • package.json
  • android/build.gradle
  • android/app/build.gradle
  • Native module changes

Manual Build Setup

1. Configure MapBox

Enter your MapBox token when prompted (same token as iOS).

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
See Receipt Scanning for more details on mobile receipt capture.

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

  1. Open Settings > About Phone
  2. Tap “Build Number” 7 times to enable Developer Options
  3. Go to Settings > Developer Options
  4. Enable “USB Debugging”
  5. Connect device via USB

Run App

For some devices, you may need to enable “Install via USB” in Developer Options.

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

New Expensify uses Hermes JS engine:
  1. Navigate to chrome://inspect
  2. Click “Configure” and add Metro server: localhost:8081
  3. Find “Hermes React Native” target
  4. Click “inspect” to open DevTools
See React Native Debugging

Testing Web in Android Emulator

To test the web app in Chrome on Android emulator:

Performance Profiling

Enable Source Maps

In android/app/build.gradle:
android/app/build.gradle

Record Performance Traces

  1. Build app in production mode
  2. Navigate to feature to profile
  3. Four-finger tap to open menu
  4. Select “Use Profiling”
  5. Interact with app
  6. Four-finger tap to stop
  7. Share trace file

Symbolicate Traces

Prebuilt React Native Artifacts

Speed up builds by using prebuilt React Native:

Enable Prebuilt Artifacts

Edit android/gradle.properties (Standalone) or Mobile-Expensify/Android/gradle.properties (HybridApp):

Configure GitHub CLI

Push Notification Setup (Development)

To receive push notifications while testing:

HybridApp

Edit Mobile-Expensify/Android/assets/airshipconfig.properties:

Standalone

Copy production config to development:

Troubleshooting

Rock Build Issues

  1. Reinstall dependencies:
  2. Run again:
  1. Clean Android directory:
  2. Try running again
  1. Check GitHub Actions: Android Builds
  2. Compare fingerprints:

Gradle Issues

Metro Bundler Issues

ADB Connection Issues

Emulator Performance

1

Enable Hardware Acceleration

In Android Studio: Tools > AVD Manager > Edit Device > Show Advanced SettingsSet:
  • Graphics: Hardware - GLES 2.0
  • Boot option: Cold boot
2

Allocate More RAM

Increase RAM in AVD settings (2048 MB minimum)
3

Use x86_64 Image

x86_64 images are faster than ARM on Intel/AMD processors

Certificate Installation Fails

If you see “adbd cannot run as root in production builds”:
See Stack Overflow solution.

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