Skip to main content
New Expensify for iOS provides a native experience with full offline support, camera receipt scanning, and platform-specific features.

Prerequisites

macOS Required: iOS development requires a Mac with Xcode installed.

System Requirements

  • macOS (latest version recommended)
  • Xcode 14.0 or later with iOS Platform package
  • Ruby (for CocoaPods)
  • Node.js 18+ and npm

For M1/M2 Macs

If using an M1 or M2 Mac, see this Stack Overflow post for CocoaPods installation.

Quick Start with Rock

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

Running the App

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

How Rock Works

  1. Fingerprint Generation: Rock creates a 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 when modified:
  • package.json
  • Podfile
  • ios/ directory contents
  • Native module changes

Manual Build Setup

For local development or when Rock remote builds aren’t available:

1. Install Ruby and Bundler

If you get permission errors, you’re using system Ruby. Install Ruby via rbenv instead.

2. Configure MapBox

Follow the prompts to enter your MapBox token. See MapBox setup guide for obtaining a token.

3. Install iOS Dependencies

4. Run the App

iOS-Specific Features

Face ID / Touch ID

Biometric authentication is supported for secure login:

Camera Receipt Scanning

iOS camera integration with permissions:
src/components/AttachmentPicker/launchCamera/launchCamera.ios.ts
See Receipt Scanning for more details on mobile receipt capture.

Live Activities (iOS 16.1+)

GPS trip tracking with Live Activities:
ios/AppDelegate.swift

Share Extension

Share receipts and files from other apps:
ios/ShareViewController/ShareViewController.swift

Push Notifications

iOS uses APNs through Airship for push notifications:
src/libs/Notification/PushNotification/index.native.ts
See Push Notifications for detailed setup and configuration.

Running on Physical Device

To run on a physical iPhone or iPad:
  1. Connect device via USB
  2. Open ios/NewExpensify.xcworkspace in Xcode
  3. Select your device from the target dropdown
  4. Click “Run” or press Cmd + R
See How to Build on Physical iOS Device for detailed instructions.

Development Workflow

Hot Reload

Changes to JavaScript/TypeScript files automatically reload:
  • Fast Refresh: Automatic for most changes
  • Manual Reload: Shake device or press Cmd + R in simulator
  • Debug Menu: Cmd + D in simulator

Debugging

  1. Enable Web Inspector in Safari: Develop > Simulator
  2. Select your app from the list
  3. Use Safari DevTools for debugging

Testing Web in iOS Simulator

To test the web app in Safari on iOS simulator:
This installs the development SSL certificate on the simulator so you can test https://dev.new.expensify.com:8082.

Performance Profiling

Enable Source Maps

In Xcode, edit the “Bundle React Native code and images” build phase:
Build Phase Script

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 again to stop
  7. Share the trace file

Symbolicate Traces

Push Notification Setup (Development)

To receive push notifications while testing against Staging/Production:

HybridApp

Edit Mobile-Expensify/iOS/AirshipConfig/Debug/AirshipConfig.plist:

Standalone

Replace development keys with production values in ios/AirshipConfig.plist:

Troubleshooting

Rock Build Issues

  1. Try reinstalling dependencies:
  2. Run the app again:
  1. Clean the iOS directory:
  2. Try running again
  1. Check if GitHub Actions completed: iOS Builds Workflow
  2. Compare fingerprints:
  3. Look for differences in fingerprint vs GitHub Actions output

CocoaPods Issues

Xcode Build Errors

1

Check Xcode Updates

System Settings > Software Update > Check for Xcode updates
2

Clean Build Folder

Product > Clean Build Folder (or Cmd + Shift + K)
3

Reset Simulator

Device > Erase All Content and Settings
4

Restart Xcode

Quit and reopen Xcode

Metro Bundler Issues

Native Modules

Creating Native iOS Modules

For advanced iOS features, create native modules:
ios/RCTShortcutManagerModule.h
ios/RCTShortcutManagerModule.m

Build Configurations

Debug vs Release

  • Debug: Fast refresh, Chrome debugging, development warnings
  • Release: Optimized bundle, no debugging, production-ready

Resources

React Native Docs

Official React Native iOS setup

Xcode Documentation

Apple’s Xcode resources

Rock Documentation

Learn more about Rock build system

Airship iOS SDK

Push notification integration

Next Steps

Receipt Scanning

Learn about mobile receipt capture

Push Notifications

Configure push notifications

Offline Mode

Understand offline functionality

Android Platform

Setup for Android development