Mobile app: development setup (Android & iOS)

The big picture

While you develop, two programs run on your PC and the app runs on your phone:

There are two ways to open the app on a phone:

Both load your latest code from your PC, so code changes never need a new build. You only rebuild a development build when native parts change (see when).

What you need

• PC: Windows 10/11 (this guide uses PowerShell) or a Mac. No Android Studio, Java or Xcode is needed — builds run in Expo's cloud.
• Phones: Android 7.0 or newer; iPhone with iOS 15.1 or newer. On the same Wi-Fi as the PC.
• Access to the SiteCash GitHub repository.
• Accounts (only for development builds): Expo (free) at expo.dev; for iPhones, the Apple Developer Program ($99 a year) at developer.apple.com.

1. Install the tools

1. Node.js (version 20 or newer, LTS recommended) from nodejs.org. It includes npm.
2. Git from git-scm.com.
3. Check both in a new PowerShell window:

   node -v      # shows e.g. v24.16.0
   npm -v
   git --version

4. EAS CLI, Expo's command-line tool for builds (needed from step 6):

   npm install -g eas-cli
   eas --version

   -g installs it for the whole PC, so the eas command works in any folder.
5. Optional: VS Code from code.visualstudio.com.

2. Get the code

cd C:\Projects
git clone https://github.com/miteshec11/sitecash.git PettyCash-RealEstate
cd PettyCash-RealEstate
npm install           # packages for the SiteCash server/website
cd mobile
npm install           # packages for the mobile app (it has its own package.json)
cd ..

If you already have the folder, just get the latest code with git pull, then run npm install in both places again (it only adds what changed).

3. Run the SiteCash server

1. Settings file. Copy the example and open it:

   Copy-Item .env.example .env.local
   notepad .env.local

   Set SESSION_SECRET to a random value of at least 32 characters (make one with the command below). Leave DATABASE_URL empty: the server then uses a built-in development database in .data/pglite, so no Postgres is needed.

   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

2. Database. Create the tables and a made-up sample company with users, sites, entries and bill photos:

   npm run db:migrate
   npx tsx scripts/seed-sample.ts

   Logins (password sample1234): kiran@sunrise.example (site user), neha@sunrise.example (accountant), ravi@sunrise.example (owner). If your database already has users, skip this step and use those logins.
3. Start the server and leave this window open:

   npm run dev

   You should see Ready. Open http://localhost:3000 on the PC and log in once to check.

4. Connect phone and PC

1. Put the phone on the same Wi-Fi as the PC (not mobile data, not a guest Wi-Fi).
2. Find the PC's Wi-Fi address:

   ipconfig

   Look under Wireless LAN adapter Wi-Fi → IPv4 Address, for example 192.168.1.11. Ignore adapters named VirtualBox/Ethernet 2 (192.168.56.x) or vEthernet (172.x.x.x) — the phone cannot reach those.
3. Test from the phone: open http://192.168.1.11:3000 in the phone's browser (use your address). The SiteCash page must appear. If it does not, see Troubleshooting (usually Windows Firewall).

5. Run the app in Expo Go (Android & iPhone)

1. Install Expo Go on the phone: Play Store (Android) or App Store (iPhone). Keep it updated — it must support Expo SDK 57.
2. Tell the app where the server is. Create mobile/.env.local (it is not committed to Git) with your Wi-Fi address:

   EXPO_PUBLIC_API_URL=http://192.168.1.11:3000
   REACT_NATIVE_PACKAGER_HOSTNAME=192.168.1.11

   EXPO_PUBLIC_API_URL is the SiteCash server the app calls. REACT_NATIVE_PACKAGER_HOSTNAME makes the QR code use your Wi-Fi address instead of a virtual adapter. When you start Expo you will see env: load .env.local.
3. In a second PowerShell window, start Expo:

   cd C:\Projects\PettyCash-RealEstate\mobile
   npx expo start

   A QR code appears. Because the project includes development-build support, it starts in development build mode. For Expo Go, press s once — the text changes to Using Expo Go.
4. Open it on the phone:
   • Android: open Expo Go → Scan QR code.
   • iPhone: open the Camera app, point at the QR code, tap the banner. When iOS asks to find devices on your local network, tap Allow.
   The first load takes up to a minute (the code is bundled); later loads are quick.
5. Log in with a user from step 3. If the app cannot reach the server, tap Server on the login screen and check the address.

Keys in the Expo window: r reload the app · m open the developer menu on the phone · s switch Expo Go / development build · w open in a web browser · ? all keys · Ctrl+C stop.

$env:EXPO_PUBLIC_API_URL = "http://192.168.1.11:3000"
$env:REACT_NATIVE_PACKAGER_HOSTNAME = "192.168.1.11"

6. Expo account (one time)

Needed for development builds, store builds and push notifications. The SiteCash app is already linked to the Expo project @dbarmai/sitecash (the id is in mobile/app.json).

cd C:\Projects\PettyCash-RealEstate\mobile
eas login        # opens the browser to sign in; the terminal waits until you finish
eas whoami       # shows the account you are signed in with

• Other developers need to be members of the Expo account or organization that owns the project (expo.dev → account → Members) to build it.
• Only for a new Expo project (not needed for SiteCash now): eas init creates it and writes its id into app.json.

7. Android development build

7a. Push notification key (one time)

Android notifications go through Google Firebase. The project already has mobile/google-services.json (Firebase project sitecash-pettycash) and app.json points to it. Expo also needs Firebase's private key:

1. Firebase console → ⚙ Project settings → Service accounts → Generate new private key. Save the file outside the project folder (for example Documents\sitecash-keys\). It is secret — never commit it.
2. Upload it to Expo:

   eas credentials

   Choose: Android → build profile development → Google Service Account → Manage your Google Service Account Key for Push Notifications (FCM V1) → Set up a Google Service Account Key for Push Notifications (FCM V1) → Upload a Google Service Account Key → type the file path (tip: Shift + right-click the file → Copy as path, then remove the quotes). Then Go back → Exit. The key belongs to the app, so it works for all build types.

7b. Build and install

eas build -p android --profile development

• -p android: platform. --profile development: the settings named "development" in mobile/eas.json (a debug app with developer tools, as an installable APK).
• The first time it asks Generate a new Android Keystore? — answer yes. This is the app's signing key; Expo stores it safely.
• The build runs in Expo's cloud (about 10–30 minutes; the free plan can queue). The terminal shows a link to follow it on expo.dev, and you get an email when it finishes.

1. Open the build link (or scan its QR code) on the Android phone and download the APK.
2. Open the downloaded file to install. Allow "install unknown apps" for your browser or Files app when Android asks.
3. Start Expo on the PC as in step 5, but don't press s — it should say Using development build.
4. Open the new SiteCash app on the phone. It shows your PC's Expo server in a list (or scan the QR code from inside it) and loads your code.

8. iPhone development build

Apple only allows your own app builds on iPhones registered in your Apple Developer account. You need the paid Apple Developer Program ($99/year; approval usually takes 1–2 days — a company account needs a D-U-N-S number first).

1. Register each iPhone (once per phone, up to 100 phones a year):

   eas device:create

   Choose Website and open the link it shows on the iPhone (in Safari). Install the profile it downloads: Settings → General → VPN & Device Management → install.
2. Build:

   eas build -p ios --profile development

   It asks you to sign in with your Apple ID (and the 2-factor code). Answer yes when it offers to create or reuse: the distribution certificate, the provisioning profile (it includes the phones you registered), and the Apple Push Notifications service key — that key makes iPhone notifications work. If you add another iPhone later, run eas device:create again and rebuild.
3. Install: open the build link on the registered iPhone and tap Install.
4. Developer Mode (iOS 16 and newer, once): Settings → Privacy & Security → Developer Mode → on → restart → confirm.
5. Run: start Expo on the PC (development build mode, as for Android) and open the SiteCash app on the iPhone. Allow the local-network question.

9. Test push notifications

Notifications only work in a development build (or later store builds), not in Expo Go.

1. In the main folder's .env.local add the line below and restart npm run dev. (In development the server otherwise only writes notifications to .data/outbox.)

   PUSH_MODE=expo

2. On the phone (development build), log in as an approver (owner, admin or accountant), e.g. neha@sunrise.example, and tap Allow when asked about notifications.
3. On the PC browser, log in as a site user, e.g. kiran@sunrise.example, and create a cash request.
4. The phone shows "… requested ₹…". Tapping it opens that request in the app. On the website's Alerts page the alert shows an App delivery chip.

How it works: after login the app asks for permission, gets an Expo push token and registers it with the server (POST /api/mobile/v1/devices/push). The server sends every alert for that user to their logged-in phones through Expo's push service, which passes it to Google (Android) or Apple (iPhone).

10. Everyday workflow

1. Window 1: npm run dev (main folder). Window 2: npx expo start (mobile/).
2. Open the app on the phone. Edit files in mobile/app or mobile/src; saving updates the phone at once (Fast Refresh). Press r to reload fully.
3. Before committing, run the checks in mobile/:

   npm run typecheck                  # TypeScript errors
   npx expo-doctor                    # Expo SDK and package health (should say all checks passed)
   npx expo export --platform web     # the app bundles without errors; then delete the dist folder

4. Commit and push as usual (git add, git commit, git push).

When do I need a new development build?

Only when native parts change: you added a package with native code (npx expo install … of an expo-* or react-native-* package), changed app.json (permissions, plugins, icon, app id), or upgraded the Expo SDK. Screens, logic and styles never need a rebuild. Expo warns you when the installed build does not match the code.

Changing the server (API) too?

The app's API is in src/app/api/mobile/v1/[...path]/route.ts, with the contract in docs/mobile-api.md. Business rules live in src/lib/services/ and are shared with the website. After changing them, run npx tsc --noEmit in the main folder.

Command reference

Where the code is

Troubleshooting

Next: when the app is ready for users, follow Publish to Play Store & App Store.