This guide will help you set up New Expensify for local development across all platforms.
Prerequisites Before you begin, ensure you have the following installed:
Node.js Version 20.20.0 (use nvm for easy version management)
npm Version 10.8.2 (comes with Node.js)
Watchman Required for React Native file watching
nvm Recommended for Node.js version management
Getting Started
Install nvm and Node.js
Install nvm, then use it to install the correct Node.js version: brew install nvm && nvm install
The project uses strict Node and npm versions defined in package.json and .nvmrc. The npm install command will fail if you’re not using the correct versions.
Install Watchman
Watchman is required for React Native’s file watching:
Install Dependencies
Install all project dependencies: For standalone builds, use: npm run install-standalone
Run the Application
Start the development server for your desired platform: # Web npm run web # iOS npm run ios # Android npm run android
Web Development Setup The webpack development server uses HTTPS. On macOS, you can run: This installs mkcert and generates valid certificates for dev.new.expensify.com and localhost. For other operating systems:
Install mkcert
Generate certificates:
mkcert -install mkcert -cert-file config/webpack/certificate.pem -key-file config/webpack/key.pem dev.new.expensify.com localhost 127.0.0.1
Add this entry to your /etc/hosts file: 127.0.0.1 dev.new.expensify.com
Run Development Server The app will be available at https://dev.new.expensify.com:8082 Build for Production To test a production build locally: # 1. Build the production bundle npm run build # 2. Run the distribution server npm run web:dist
Access at http://localhost:8080 iOS Development Setup New Expensify uses Rock to manage native builds. Rock downloads prebuilt artifacts from S3, reducing the need for local compilation. Prerequisites
Install Xcode
Install Xcode and the iOS Platform package
Check System Settings for Xcode updates after installation
Install Ruby and Bundler # Install bundler gem install bundler # Install project gems bundle install
If you get Gem::FilePermissionError, you’re using system Ruby. Install Ruby with rbenv instead.
Configure MapBox Follow the instructions to obtain a MapBox token.
Install iOS Dependencies npm install && npm run pod-install
Run the App Start Metro server in one terminal: In another terminal, run the iOS app: # Standalone app npm run ios-standalone # Hybrid app npm run ios
Troubleshooting If you encounter build issues:
Re-install dependencies:
npm run i-standalone # For standalone npm install # For hybrid
Clean iOS directory:
git clean -fdx ios/ # Standalone git clean -fdx ./Mobile-Expensify # Hybrid
Check iOS build workflows on GitHub
Android Development Setup New Expensify uses Rock to manage native builds. Rock downloads prebuilt artifacts from S3, reducing the need for local compilation. Prerequisites
Configure MapBox Follow the instructions to obtain a MapBox token (if you haven’t done this for iOS).
React Native Environment
Follow the official React Native Android setup guide
Install ccache (Optional)
ccache significantly reduces C/C++ compilation times:View cache statistics:
Run the App Start Metro server in one terminal: In another terminal, run the Android app: # Standalone app npm run android-standalone # Hybrid app npm run android
Troubleshooting If you encounter build issues:
Re-install dependencies:
npm run i-standalone # For standalone npm install # For hybrid
Clean Android directory:
git clean -fdx android/ # Standalone git clean -fdx ./Mobile-Expensify # Hybrid
Check Android build workflows on GitHub
Environment Variables Creating a .env file is not necessary for external contributors. It can lead to errors when variables get updated since your local .env file is ignored.
Key Environment Variables Variable Description NEW_EXPENSIFY_URLRoot URL for the website SECURE_EXPENSIFY_URLURL for the Expensify secure API EXPENSIFY_URLURL for the Expensify API EXPENSIFY_PARTNER_NAMEConstant for app authentication EXPENSIFY_PARTNER_PASSWORDConstant for app authentication (OK to be public) PUSHER_APP_KEYKey for Pusher.com authentication USE_WEB_PROXYStart proxy server for API requests (set to true for external contributors)
Variable Description CAPTURE_METRICSCapture performance metrics in Flipper ONYX_METRICSCapture additional performance metrics USE_WDYREnable Why Did You Render testing USE_REDUX_DEVTOOLSEnable Redux DevTools for Onyx state debugging
If your .env changes aren’t working, try rm -rf .rock and re-run your platform command.
Running Tests Unit Tests
Type Checking
Linting
Performance Tests
Common Issues
If you see CORS errors in the browser console: Access to fetch at 'https://www.expensify.com/api/BeginSignIn' from origin 'http://localhost:8080' has been blocked by CORS policy
You likely have a misconfigured .env file. Remove it and try again:
If npm install fails with a version error:
Install nvm: brew install nvm
Use the correct version: nvm install
Set up automatic switching for zsh or bash
If you’re having HTTPS certificate issues:
Ensure mkcert is installed: brew install mkcert
Run: npm run setup-https
Check that /etc/hosts contains: 127.0.0.1 dev.new.expensify.com
If you’re having MapBox SDK download issues:
Run: npm run configure-mapbox
Follow the prompts to set up your token
See this Slack thread for Expensify employees
Next Steps
Authentication Learn how to sign in and manage your session
Workspaces Create and configure your first workspace
Contributing Start contributing to the project
Architecture Understand the codebase structure
