callstack / callstack/agent-device

iOS Metro hint doesn't reach expo-dev-client apps (writes bare-RN RCT_jsLocation only)

Open
#1,245 0 comments 0 reactions 0 assignees View on GitHub
bug ready-for-agent
Dominant language
TypeScript
Stars
4.6k
Forks
299
Avg merge
10h 17m
Merged PRs (30d)
515

Description

## Summary

On iOS, agent-device's Metro/dev-server runtime hint (`open --metro-host/--metro-port`, `metro reload`, `metro prepare`) does **not** point an **expo-dev-client** app at the chosen Metro server. It writes bare-React-Native's `RCT_jsLocation` preference, which an expo-dev-client ignores — so the app keeps loading from its own dev-server URL (or embedded bundle) instead of the requested port.

This is the iOS analogue of the Android `debug_http_host`-wrong-file bug fixed in #1242: the *intent* is right, but the *mechanism* targets bare-RN while the app framework (expo-dev-client) reads a different source.

## Root cause

`applyIosSimulatorRuntimeHints` in `src/daemon/runtime-hints.ts` sets `RCT_jsLocation` (+ `RCT_packager_scheme`) in the app's NSUserDefaults via `simctl`. Bare RN's `RCTBundleURLProvider` reads `RCT_jsLocation`, so this works for bare-RN debug apps. But an **expo-dev-client** resolves its dev-server from its own launcher state / the `exp+://expo-development-client/?url=` deep-link, not `RCT_jsLocation` — so the hint is silently a no-op.

## Evidence (verified live, iPhone 17 Pro simulator)

- After `open com.callstack.agentdevicelab --metro-host 127.0.0.1 --metro-port 8085`, `defaults read com.callstack.agentdevicelab RCT_jsLocation` returned `127.0.0.1:8085` — the hint **was written correctly**.
- The app nonetheless did **not** request a bundle from Metro on 8085 (Metro logged only "Waiting on http://localhost:8085"); it kept running its own bundle.
- The dev build **does** register the `exp+agent-device-test-app` URL scheme (the expo-dev-client launcher handler), confirming it is an expo-dev-client and that the `exp+…://expo-development-client/?url=` path is the intended mechanism.

## Suggested fix direction

Detect an expo-dev-client target (it registers an `exp+` `CFBundleURLScheme` in `Info.plist`) and, for those, point Metro via the expo mechanism instead of `RCT_jsLocation`:

- Launch/redirect via `xcrun simctl openurl "exp+://expo-development-client/?url="`.
- agent-device already computes the correct expo bundle URL via `metro prepare --kind expo` (`.expo/.virtual-metro-entry.bundle`), so the pointing side is the gap.

## Important caveat (separate limitation)

An **embed-first** dev build — one shipped with a baked `main.jsbundle` and configured to launch straight into the embedded bundle rather than the dev-launcher — runs the embedded bundle regardless of any metro hint or deep-link. That case genuinely requires a native rebuild (`expo run:ios`) and is **not** solvable by the fix above; only launcher-style expo-dev-clients benefit.

## Context

Surfaced while capturing live over-filtering evidence for the replay-divergence chrome filter (PR #1233). Related: #1242 (the Android `debug_http_host` counterpart).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.