highperfocused/multica
1
0
Fork 0
mirror of https://github.com/multica-ai/multica.git synced 2026-07-27 21:33:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(mobile): correct Debug-vs-Release standalone claim and env reload semantics

Browse Source 
Two corrections to docs landed earlier this branch:

- The README told self-host users that ios:device:staging "runs without
  the Mac after the build completes." That is wrong for the Debug build
  it produces: every launch the embedded expo-dev-launcher probes Metro,
  showing a "Downloading…" / Recently-opened screen and stalling when the
  Mac is asleep or unreachable. Split the section into two paths and
  recommend the new :release variant for standalone use.

- The .env.example said changing a value "requires re-running an ios:*
  build" and that "dev:* (Metro) alone will not refresh baked-in values."
  That is only true for an installed Release build. For Debug, restarting
  Metro is sufficient — it re-reads .env on startup and inlines the new
  values into the next JS bundle it serves. Rewrite the comment to
  distinguish the two cases.

Also drop stale references to the removed ios:mobile:sim* scripts from
the env example.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Naiyuan Qing
2026-05-15 21:27:54 +08:00
parent de235fd5fd
commit e4ecb722fe
2 changed files with 42 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
apps/mobile/.env.example
View File

@@ -1,16 +1,19 @@
# Mobile env template — copy this to one of:
# .env.development.local (used by `*:mobile` — local backend)
# .env.staging (used by `*:mobile:staging` — remote staging)
# .env.development.local (used by `*:mobile` — local backend)
# .env.staging (used by `*:mobile:staging` — remote staging)
#
# All six mobile scripts read one of these two files, depending on suffix:
# dev:mobile / dev:mobile:staging — Metro only
# ios:mobile:sim / ios:mobile:sim:staging — build + install onto Simulator
# ios:mobile:device / ios:mobile:device:staging — build + install onto physical iPhone
# All five mobile scripts read one of these two files, depending on suffix:
# dev:mobile / dev:mobile:staging — Metro only
# ios:mobile:device / ios:mobile:device:staging — Debug build to iPhone
# ios:mobile:device:staging:release — Release build to iPhone
#
# Variables are baked into the JS bundle at build time, NOT read at runtime.
# After changing this file, you must re-run an `ios:*` build for changes to
# take effect on an installed app — `dev:*` (Metro) alone will not refresh
# baked-in values.
# How EXPO_PUBLIC_* values reach the installed app:
# - Metro reads this file once at startup and inlines the values into every
# JS bundle it serves. Editing the file mid-session does NOT auto-refresh
# — restart Metro (Ctrl+C, then re-run `dev:mobile*`) to pick up changes.
# - For an installed Release build the value is baked into the embedded
# bundle at `ios:*:release` time; the only way to change it is to re-run
# the release build.
#
# Phone must be able to reach this URL. For local dev use your Mac's LAN IP
# (run `ipconfig getifaddr en0`), not `localhost` / `127.0.0.1`.

46
apps/mobile/README.md
View File

@@ -4,39 +4,51 @@ Expo + React Native iOS client for Multica. Independent from web/desktop — sha
## Scripts
| Command | Env file | Backend |
| Command | What it does | Backend |
|---|---|---|
| `pnpm dev:mobile` | `.env.development.local` | your own (LAN IP of local backend) |
| `pnpm dev:mobile:staging` | `.env.staging` | staging |
| `pnpm ios:mobile:device` | `.env.development.local` | your own |
| `pnpm ios:mobile:device:staging` | `.env.staging` | staging |
| `pnpm dev:mobile` | Metro only (reuse existing dev install) | local (`.env.development.local`) |
| `pnpm dev:mobile:staging` | Metro only (reuse existing dev install) | staging (`.env.staging`) |
| `pnpm ios:mobile:device` | Full rebuild + install on USB iPhone, **Debug** | local |
| `pnpm ios:mobile:device:staging` | Full rebuild + install on USB iPhone, **Debug** | staging |
| `pnpm ios:mobile:device:staging:release` | Full rebuild + install, **Release** (standalone) | staging |
`dev:*` runs Metro only (reuse an already-installed dev-client build). `ios:device:*` does a full native rebuild + install onto a physically-connected iPhone.
`dev:*` runs Metro only — assumes a Debug build of the matching variant is already installed on the device. `ios:device:*` does a full native rebuild + install onto a USB-connected iPhone.
Bundle identifier and display name switch on `APP_ENV` (see `app.config.ts`), so Dev / Staging / Production variants can coexist on the same device.
## Build your own version onto your iPhone
For a self-host user who wants to run Multica mobile against their own / staging backend:
Two paths, depending on what you want to do:
1. Get the prerequisites set up (Mac, Xcode, free Apple ID added in Xcode → Settings → Accounts, iPhone connected, Developer Mode enabled). Follow Expo's [Set up your environment](https://docs.expo.dev/get-started/set-up-your-environment/) — pick **Development build → iOS Device**.
2. Copy `.env.example` to `.env.staging` (or `.env.development.local`) and set `EXPO_PUBLIC_API_URL` to the backend you want to hit.
3. From repo root, run:
### Day-to-day development (you have the Mac in front of you)
```bash
pnpm ios:mobile:device:staging
```
```bash
pnpm ios:mobile:device:staging
```
First build downloads CocoaPods + compiles React Native from source — expect 10-20 minutes. Subsequent builds are much faster.
Produces a **Debug build** with `expo-dev-launcher` embedded. Every launch the app probes Metro on your Mac and pulls fresh JS — perfect for hot-reload, painful when the Mac is asleep or you're on a different WiFi.
The app installs to your phone and runs without the Mac after the build completes.
### Standalone / "just use it" (you want to walk away from the Mac)
```bash
pnpm ios:mobile:device:staging:release
```
Produces a **Release build**. No `expo-dev-launcher`, no Metro probe, no "Downloading…" screen. Splash → app, exactly like an App Store install. The trade-off: you cannot hot-reload — every JS change requires re-running this command.
Both paths share the same prerequisites: Mac with Xcode, free Apple ID added under Xcode → Settings → Accounts, iPhone connected via USB with Developer Mode enabled. Follow Expo's [Set up your environment](https://docs.expo.dev/get-started/set-up-your-environment/) — pick **Development build → iOS Device** — if any of that is missing.
First build of either variant downloads CocoaPods + compiles React Native from source — expect 10-20 minutes. Subsequent builds reuse Xcode's DerivedData cache.
## 7-day signing limit
A free Apple ID signs builds for **7 days only**. After that the app refuses to launch. Plug back into the Mac and re-run `pnpm ios:mobile:device:staging` to re-sign — there is no workaround short of an Apple Developer Program account ($99/yr).
A free Apple ID signs builds for **7 days only**, Debug and Release both. After that the app refuses to launch. Plug back into the Mac and re-run the corresponding `ios:*` script to re-sign. The only workaround is an Apple Developer Program account ($99/yr), which extends to 1 year.
## Pointing at a different backend
Edit `EXPO_PUBLIC_API_URL` in `.env.staging` (or `.env.development.local`), then rebuild. The value is baked into the JS bundle at compile time; runtime swaps are not supported.
Edit `EXPO_PUBLIC_API_URL` in `.env.staging` (or `.env.development.local`). Then:
- For an installed **Debug build**: restart Metro (`pnpm dev:mobile:staging`) so the next JS bundle it serves picks up the new value.
- For an installed **Release build**: re-run the `ios:*:release` command — the value is baked into the embedded bundle at build time.
For local backend testing, use your Mac's LAN IP (`ipconfig getifaddr en0`), not `localhost`.