Additional Reading

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

---

Local development

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

Getting Started

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

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

Recommended node setup

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.

Platform-Specific Setup

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.

General Troubleshooting

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)
   copy

   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.

Environment variables

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
• 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

---

Running the tests

Unit tests

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

Performance tests

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

CodeCov

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

---