Installation & Setup - New Expensify

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:

brew install watchman

Install Dependencies

Install all project dependencies:

npm install

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

Platform-Specific Setup

Web
iOS
Android

Web Development Setup

Configure HTTPS

The webpack development server uses HTTPS. On macOS, you can run:

npm run setup-https

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

Configure Local Hosts

Add this entry to your /etc/hosts file:

127.0.0.1 dev.new.expensify.com

Run Development Server

npm run web

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
npm run 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:

npm run start

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
npm run 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:
brew install ccache
View cache statistics:
ccache --show-stats

Run the App

Start Metro server in one terminal:

npm run start

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_URL`	Root URL for the website
`SECURE_EXPENSIFY_URL`	URL for the Expensify secure API
`EXPENSIFY_URL`	URL for the Expensify API
`EXPENSIFY_PARTNER_NAME`	Constant for app authentication
`EXPENSIFY_PARTNER_PASSWORD`	Constant for app authentication (OK to be public)
`PUSHER_APP_KEY`	Key for Pusher.com authentication
`USE_WEB_PROXY`	Start proxy server for API requests (set to `true` for external contributors)

Optional Performance Variables

Variable	Description
`CAPTURE_METRICS`	Capture performance metrics in Flipper
`ONYX_METRICS`	Capture additional performance metrics
`USE_WDYR`	Enable Why Did You Render testing
`USE_REDUX_DEVTOOLS`	Enable 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

npm run test

npm run typecheck

npm run lint

npm run perf-test

Common Issues

CORS Errors

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:

rm .env

Node Version Mismatch

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

Certificate Issues (Web)

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

MapBox Token Issues

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

​Prerequisites

Node.js

npm

Watchman

nvm

​Getting Started

​Platform-Specific Setup

​Web Development Setup

​Configure HTTPS

​Configure Local Hosts

​Run Development Server

​Build for Production

​iOS Development Setup

​Prerequisites

​Run the App

​Troubleshooting

​Android Development Setup

​Prerequisites

​Run the App

​Troubleshooting

​Environment Variables

​Key Environment Variables

​Optional Performance Variables

​Running Tests

​Common Issues

​Next Steps

Authentication

Workspaces

Contributing

Architecture

Prerequisites

Getting Started

Platform-Specific Setup

Web Development Setup

Configure HTTPS

Configure Local Hosts

Run Development Server

Build for Production

iOS Development Setup

Prerequisites

Run the App

Troubleshooting

Android Development Setup

Prerequisites

Run the App

Troubleshooting

Environment Variables

Key Environment Variables

Optional Performance Variables

Running Tests

Common Issues

Next Steps