Prerequisites
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
How Rock Works
- Fingerprint Generation: Rock creates a 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.jsonPodfileios/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
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
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:- Connect device via USB
- Open
ios/NewExpensify.xcworkspacein Xcode - Select your device from the target dropdown
- Click “Run” or press
Cmd + R
Development Workflow
Hot Reload
Changes to JavaScript/TypeScript files automatically reload:- Fast Refresh: Automatic for most changes
- Manual Reload: Shake device or press
Cmd + Rin simulator - Debug Menu:
Cmd + Din simulator
Debugging
- Safari Web Inspector
- Flipper
- React DevTools
- Enable Web Inspector in Safari: Develop > Simulator
- Select your app from the list
- Use Safari DevTools for debugging
Testing Web in iOS Simulator
To test the web app in Safari on iOS simulator: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
- 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 again to stop
- Share the trace file
Symbolicate Traces
Push Notification Setup (Development)
To receive push notifications while testing against Staging/Production:HybridApp
EditMobile-Expensify/iOS/AirshipConfig/Debug/AirshipConfig.plist:
Standalone
Replace development keys with production values inios/AirshipConfig.plist:
Troubleshooting
Rock Build Issues
App triggers full build unexpectedly
App triggers full build unexpectedly
- Try reinstalling dependencies:
- Run the app again:
Build still failing after reinstall
Build still failing after reinstall
- Clean the iOS directory:
- Try running again
Fingerprint mismatch
Fingerprint mismatch
- Check if GitHub Actions completed: iOS Builds Workflow
-
Compare fingerprints:
- Look for differences in fingerprint vs GitHub Actions output
CocoaPods Issues
Xcode Build Errors
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
