Mobile

The mobile app lives in apps/mobile. It is an Expo app with expo-router and NativeWind. Same typed HyperFetch SDK as the web app, same theme tokens, same Hono API.

pnpm dev starts Metro with the rest of the stack. You can also start just the mobile app.

Develop locally

Copy the env file if you have not already:

cp apps/mobile/.env.example apps/mobile/.env

The default API URL is http://localhost:3000. That is correct for the iOS Simulator and the Android emulator. A physical phone cannot reach localhost on your computer. Use your machine's LAN address instead. See Talk to the local API.

Start Metro on its own:

pnpm --filter @hype-stack/mobile serve

Or start everything, including Metro, from the repo root:

pnpm dev

Metro prints a QR code. Scan it with Expo Go.

Install Expo Go

Do not install Expo Go from the App Store for this project. That binary is pinned to one SDK, and this app uses a newer one. The store app will refuse to open the project.

Install a matching Expo Go from sign.expo.dev.

1. Open sign.expo.dev.
2. Pick the SDK that matches the expo version in apps/mobile/package.json. Today that is SDK 56.
3. Sign in with your Expo account.
4. Select the iPhone or iPad you will use.
5. Sign with your Apple ID. Expo uses it only as a temporary signing proxy and does not store the credentials.
6. Install over USB or by scanning the QR code Expo shows.

If iOS asks, turn on Developer Mode: Settings, Privacy & Security, Developer Mode.

Android

Install Expo Go from the Play Store. If it complains about the SDK version, the store build is behind. Use an emulator, or ship a development build with deploy mobile.

Open the project

1. Put the phone and the computer on the same Wi-Fi.
2. Keep Metro running.
3. Scan the QR code from the terminal (or the Expo Dev Tools page) with Expo Go.

Edits under apps/mobile hot-reload. Restart Metro after you change any EXPO_PUBLIC_* variable. Those values are inlined when the bundle is built.

Talk to the local API

On a physical device, localhost is the phone. Point the app at your computer:

# apps/mobile/.env
EXPO_PUBLIC_API_BASE_URL=http://192.168.1.20:3000
EXPO_PUBLIC_ENVIRONMENT=development

Find the LAN IP with ipconfig getifaddr en0 on macOS, or ip addr on Linux. Restart Metro after saving.

The home screen shows a backend status badge. If it stays unreachable, the phone cannot see that URL. Check Wi-Fi, the IP, and that the backend is up on port 3000.

Simulators can keep http://localhost:3000.

Simulator and emulator

# iOS Simulator (Xcode required)
pnpm --filter @hype-stack/mobile ios

# Android emulator (Android Studio required)
pnpm --filter @hype-stack/mobile android

# Browser, for a quick layout check only
pnpm --filter @hype-stack/mobile web

The web target is not a substitute for a device. Use it to glance at layout, then confirm in Expo Go.

Tests

Mobile tests use Vitest with vitest-native and Testing Library for React Native. They sit next to the screens they cover, same as the frontend.

pnpm --filter @hype-stack/mobile test
pnpm --filter @hype-stack/mobile typecheck

Folder structure

apps/mobile/src/
  api/           # HyperFetch client and typed SDK
  assets/        # App icon, splash, images
  components/    # Shared UI
  env/           # EXPO_PUBLIC_* validation
  hooks/         # Shared hooks
  lib/           # Shared helpers
  routes/        # expo-router file-based screens
  testing/       # Test setup
  global.css     # NativeWind theme tokens

Packs add screens under src/routes and feature modules next to them.

Ship

Store builds go through EAS. See deploy mobile.

Related

• Installation
• Commands
• Testing
• Deploy