Source: https://www.hype-stack.dev/docs/mobile

# 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:

```bash
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](#talk-to-the-local-api).

Start Metro on its own:

```bash
pnpm --filter @hype-stack/mobile serve
```

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

```bash
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](https://sign.expo.dev/).

1. Open [sign.expo.dev](https://sign.expo.dev/).
2. Pick the SDK that matches the `expo` version in `apps/mobile/package.json`. Today that is SDK 57.
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](https://play.google.com/store/apps/details?id=host.exp.exponent) 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`](/docs/cli/deploy).

## 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:

```bash
# 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

```bash
# 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.

```bash
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`](/docs/cli/deploy).

## Related

- [Installation](/docs/getting-started/installation)
- [Commands](/docs/development/commands)
- [Testing](/docs/development/testing)
- [Deploy](/docs/cli/deploy)