New Expensify

• Local Development
• Platform-Specific Setup
• Testing on browsers in simulators and emulators
• Running The Tests

• Application Philosophy
• API Details
• Contributing to Expensify
• Expensify Code of Conduct
• Contributor License Agreement
• React StrictMode
• Left Hand Navigation (LHN)
• HybridApp - additional info & troubleshooting

These instructions should get you set up ready to work on New Expensify 🙌

1. Install nvm then node & npm: brew install nvm && nvm install
2. Install watchman: brew install watchman
3. Install dependencies: npm install
4. Run the specific platform with the following command: npm run <platform>, e.g. npm run web

For web, normal setup also installs the Cloudflare Worker tooling. After the HTTPS/hosts setup, npm run web serves the app through the local Worker at https://dev.new.expensify.com:8082/, with CSP, security headers, React Fast Refresh, and automatic Worker source reload. No ngrok, Cloudflare account, or web build is required.

You can use any IDE or code editing tool for developing on any platform. Use your favorite!

In order to have more consistent builds, we use a strict node and npm version as defined in the package.json engines field and .nvmrc file. npm install will fail if you do not use the version defined, so it is recommended to install node via nvm for easy node version management. Automatic node version switching can be installed for zsh or bash using nvm.

For detailed setup instructions for each platform, see the following guides:

• 🕸 Web Development: Web Setup Instructions
• 📱 iOS Development: iOS Setup Instructions
• 🤖 Android Development: Android Setup Instructions

Optional AI-assisted mobile testing: If you use Claude Code, the /agent-device skill drives iOS and Android simulators or devices for interactive testing, debugging, and performance profiling. Requires npm install -g agent-device.

1. If you are having issues with Getting Started, please reference React Native's Documentation
2. If you are running into CORS errors like (in the browser dev console)

   Access to fetch at 'https://www.expensify.com/api/BeginSignIn' from origin 'http://localhost:8080' has been blocked by CORS policy

   You probably have a misconfigured .env file - remove it (rm .env) and try again.

Note: Expensify engineers that will be testing with the API in your local dev environment please refer to these additional instructions.

Creating an .env file is not necessary. We advise external contributors against it. It can lead to errors when variables referenced here get updated since your local .env file is ignored.

• NEW_EXPENSIFY_URL - The root URL used for the website
• SECURE_EXPENSIFY_URL - The URL used to hit the Expensify secure API
• EXPENSIFY_URL - The URL used to hit the Expensify API
• EXPENSIFY_PARTNER_NAME - Constant used for the app when authenticating.
• EXPENSIFY_PARTNER_PASSWORD - Another constant used for the app when authenticating. (This is OK to be public)
• PUSHER_APP_KEY - Key used to authenticate with Pusher.com
• SECURE_NGROK_URL - Secure URL used for ngrok when testing
• NGROK_URL - URL used for ngrok when testing
• USE_NGROK - Flag to turn ngrok testing on or off
• USE_WDYR - Flag to turn Why Did You Render testing on or off
• USE_REDUX_DEVTOOLS - Flag to enable Redux DevTools for Onyx state debugging
• USE_WEB_PROXY⚠️- Used in web development, it starts a server along the local development server to proxy requests to the backend. External contributors should set this to true otherwise they'll have CORS errors. If you don't want to start the proxy server set this explicitly to false
• USE_CLOUDFLARE_WORKER - Defaults to true for npm run web. Set to false to serve Rsbuild directly over HTTPS. This does not disable the API proxy.
• WEB_PORT - Browser-facing development port (default: the first free port from 8082). An explicit port must be free.
• WEB_INTERNAL_PORT - Internal loopback HTTP Rsbuild port when the Worker is enabled (default: the next free port after WEB_PORT).
• WEB_OPEN - Set to false to suppress automatic browser opening, for example in browser automation.
• CAPTURE_METRICS (optional) - Set this to true to capture performance metrics and see them in Flipper see PERFORMANCE.md for more information
• ONYX_METRICS (optional) - Set this to true to capture even more performance metrics and see them in Flipper see React-Native-Onyx#benchmarks for more information

If your changes to .env aren't having an effect, try rm -rf .rock, then re-run npm run ios or npm run android

Unit tests are valuable when you want to test one component. They should be short, fast, and ideally only test one thing. Often times in order to write a unit test, you may need to mock data, a component, or library. We use the library Jest to help run our Unit tests.

• To run the Jest unit tests: npm run test
• To run the Bun tests — server/ plus the .github/ and scripts/ tooling tests: npm run test:bun — see tests/tooling/README.md
• UI tests guidelines can be found here

We use Reassure for monitoring performance regression. More detailed information can be found here:

CodeCov is the service we use to measure and track code coverage. You can find out more about it here