Expo + React Native Build Guide (Xcode 16.3 + macOS 15 + iOS 18)

Expo + React Native Build Guide (Xcode 16.3 · macOS 15 · iOS 18)

This guide documents common compatibility issues and solutions when building an Expo + React Native project using:

Xcode 16.3
macOS 15 (Sequoia)
iOS SDK 18.4
Expo SDK 50+
React Native 0.76+

1. System Compatibility

Ensure you’re running:

macOS 15.x (Sequoia)
Xcode 16.3 or newer
iOS SDK 18.4

Note: If Xcode is stuck at “Waiting for device…”, this is often caused by a version mismatch between macOS, iOS SDK, and the iPhone OS.

2. Required Dependencies

To avoid build errors, align your project dependencies with compatible versions:

{
  "@rnmapbox/maps": "^10.1.38",
  "expo": "^52.0.46",
  "react-native": "0.76.9",
  "expo-dev-menu": "^6.0.25"
}

3. Deprecated Packages

Remove the following dependency from your project:

1	- "ffmpeg-kit-react-native": "^6.0.2"

This package is officially retired and no longer provides iOS binaries as of April 2025.

Next Step: Replace with a new video conversion solution.

4. Mapbox Compatibility

Mapbox SDK versions below 11.6.0 may cause Swift type errors when building on Xcode 16+. Set the Mapbox iOS SDK version explicitly in app.json:

"expo": {
  "plugins": [
    [
      "@rnmapbox/maps",
      {
        "RNMapboxMapsVersion": "11.6.0"
      }
    ]
  ]
}

Related issue: Mapbox GitHub Issue #3625

5. Connect iPhone to Mac

Use a USB-C cable.
Open Xcode and navigate to Devices and Simulators.
If your iPhone requires a specific iOS SDK version, download and install it.
Unlock the device and tap Trust This Computer when prompted.

6. Signing and Capabilities in Xcode

To run the app on a physical device, enable signing:

Open the workspace in Xcode:
ios/Wander.xcworkspace
Select the project and then the target (Wander).
Go to the Signing & Capabilities tab.
Enable Automatically manage signing.
Add your Apple Developer account.
Ensure a provisioning profile is selected.

Common Error:

1	No profiles for 'one.wander[your app identifer]' were found

This occurs when signing is disabled or the profile is missing.

7. List Available Devices

Simulators only:

1	xcrun simctl list devices

All connected devices (physical + simulators):

1	xcrun xctrace list devices

Example output:

== Devices ==
Ray16Pro (18.3.2) (00000000-001A60A914FB001D)

== Simulators ==
iPhone 16 Pro (18.4) (F6A9A538-CCE4-4275-B2AA-B700F87A2B33)
...

8. Run App on Physical Device

Use the UDID from the device list:

1	npx expo run:ios --device 00000000-001A60A914FB001D

Make sure the iPhone is unlocked and trusted, and signing is properly set.

9. Additional Build Errors and Fixes

react-native-safe-area-context

Error:

1	no member named 'unit' in 'facebook::yoga::StyleLength'

Fix:

1	expo install react-native-safe-area-context

react-native-reanimated

Error:

1	mutation.parentShadowView.tag // no longer exists in ShadowViewMutation

Fix:

1	npm install react-native-reanimated@latest

Error:

1 2	self.rootViewFactory.bridge = bridge // 'rootViewFactory' must be called as a method

Fix:

1	expo install expo-dev-menu

Or manually update the code to use rootViewFactory() instead of rootViewFactory.

10. Final Checklist

Run npx expo install --fix
Clean pods: rm -rf ios/Pods && pod install --repo-update
Upgrade native modules (reanimated, safe-area-context, screens)
Remove deprecated packages (ffmpeg-kit-react-native)
Set Mapbox iOS SDK version to 11.6.0
Enable code signing in Xcode
Run app using expo run:ios --device <UDID>

Welcome to Ray's Blog

Expo + React Native Build Guide (Xcode 16.3 + macOS 15 + iOS 18)