Summary
Building the iOS app on a fresh machine (especially Xcode 26) has several prerequisites that aren't documented and produce confusing failures when missing.
To document
- Node path for Xcode script phases — resolved via
ios/.xcode.env (command -v node) with an optional ios/.xcode.env.local override. A stale .xcode.env.local (e.g. pointing at a removed nvm version) makes every RN script phase fail; because the Hermes "Replace Hermes" phase runs first, it looks like a Hermes problem when it's really "node not found". Document how to set it and this failure mode.
- Xcode 26 / iOS 26 SDK — the
fmt consteval issue and the Podfile post_install patch that works around it (link the RN-upgrade issue).
- CocoaPods locale — under a non-UTF-8 locale,
pod install can crash with Unicode Normalization not appropriate for ASCII-8BIT (Encoding::CompatibilityError). Run with LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8.
- Simulator —
dev.sh matches iPhone 16 (; document creating that sim (or relaxing the match to accept e.g. iPhone 16e).
- Maestro e2e — requires Java 17 (
JAVA_HOME=/opt/homebrew/opt/openjdk@17) plus the maestro CLI on PATH.
Acceptance
Summary
Building the iOS app on a fresh machine (especially Xcode 26) has several prerequisites that aren't documented and produce confusing failures when missing.
To document
ios/.xcode.env(command -v node) with an optionalios/.xcode.env.localoverride. A stale.xcode.env.local(e.g. pointing at a removed nvm version) makes every RN script phase fail; because the Hermes "Replace Hermes" phase runs first, it looks like a Hermes problem when it's really "node not found". Document how to set it and this failure mode.fmtconsteval issue and the Podfilepost_installpatch that works around it (link the RN-upgrade issue).pod installcan crash withUnicode Normalization not appropriate for ASCII-8BIT (Encoding::CompatibilityError). Run withLANG=en_US.UTF-8 LC_ALL=en_US.UTF-8.dev.shmatchesiPhone 16 (; document creating that sim (or relaxing the match to accept e.g.iPhone 16e).JAVA_HOME=/opt/homebrew/opt/openjdk@17) plus the maestro CLI onPATH.Acceptance