iOS for React Native developers — the native half

react-native · folio

In one line: The iOS app is an ordinary Xcode project whose dependencies come from CocoaPods (pod install turns node_modules podspecs into Pods.xcodeproj), whose build phases bundle your JS, and whose Info.plist, entitlements, privacy manifest and signing are yours to get right — most “RN build errors” are one of those phases failing.

Download PDF Print view LaTeX source

iOS for React Native developers — the native half — figure 1

Podfile and pod install

platform :ios, min_ios_version_supported   # 15.1 in 0.85
prepare_react_native_project!
linkage = ENV['USE_FRAMEWORKS']              # static | dynamic
use_frameworks! :linkage => linkage.to_sym if linkage
target 'App' do
  config = use_native_modules!               # autolinking
  use_react_native!(:path => config[:reactNativePath],
    :app_path => "#{Pod::Config.instance.installation_root}/..")
  post_install do |installer|
    react_native_post_install(installer, config[:reactNativePath])
  end
end
  • pod install resolves every native dep’s podspec, runs Codegen, writes Pods.xcodeproj + the workspace. Any native dep change, RN upgrade or Podfile edit ⇒ cd ios && bundle exec pod install (the Gemfile pins CocoaPods).
  • use_frameworks! (CocoaPods default linkage: dynamic) builds pods as frameworks; RN Firebase on CocoaPods needs :linkage => :static (it now defaults to SwiftPM). Unset, pods are static libraries.
  • Since 0.84 the RN core is precompiled (RCT_USE_PREBUILT_RNCORE=0 builds from source); you can’t step into RN internals.
  • CocoaPods trunk goes read-only on 2 Dec 2026; RN 0.87 adds experimental, opt-in SwiftPM (npx react-native spm) — CocoaPods stays default.

AppDelegate — Swift since 0.77

One AppDelegate.swift replaced main.m + AppDelegate.h/.mm. It builds a RCTReactNativeFactory(delegate:) whose ReactNativeDelegate (RCTDefaultReactNativeFactoryDelegate) returns bundleURL() — Metro in DEBUG, main.jsbundle otherwise — sets dependencyProvider = RCTAppDependencyProvider() (0.77+: forget it and third-party modules misbehave), then startReactNative(withModuleName:in:). C++ TurboModules still need an ObjC++ AppDelegate. iOS 27 SDK requires the UIScene life cycle (WWDC26, TN3187: built with Xcode 27 without it, the app won’t launch); the template adopted a SceneDelegate in Sep 2026 — deep links move to scene(_:openURLContexts:) → RCTLinkingManager.

Privacy manifest

PrivacyInfo.xcprivacy: required-reason APIs (template: FileTimestamp C617.1, UserDefaults CA92.1, SystemBootTime 35F9.1), collected data types, tracking domains. SDKs on Apple’s list ship their own signed manifest; Xcode’s privacy report aggregates them. Since 1 May 2024 App Store Connect refuses uploads missing a reason (ITMS-91053).

Info.plist — the keys you will be asked about

  • Usage descriptions: NSCameraUsageDescription, NSMicrophoneUsage…, NSPhotoLibraryUsage… (+ …AddUsage…), NSLocationWhenInUseUsage…, NSLocationAlwaysAndWhenInUseUsage…, NSFaceIDUsage…, NSBluetoothAlwaysUsage…, NSContactsUsage…, NSUserTrackingUsage… (ATT). Missing → “the system terminates your app” (Apple) at first access; vague text → review rejection(unverified). A JS permission library does not add them — you (or a config plugin) do.
  • Also: CFBundleURLTypes (schemes), LSApplicationQueriesSchemes (canOpenURL list), UIBackgroundModes, UIAppFonts, ITSAppUsesNonExemptEncryption, ATS.

Capabilities = entitlement + App ID + profile

A capability (Signing & Capabilities tab) is three things that must agree: a key in App.entitlements · the feature enabled on the App ID · a provisioning profile that contains it. Keys: aps-environment (push), com.apple.developer.associated-domains (applinks:example.com), com.apple.security.application-groups, keychain-access-groups. Signing: automatic (team id, Xcode manages profiles) or manual (fastlane match in CI); dev vs distribution cert; bundle id = App ID.

Reset recipe (in this order)

Clean Build Folder (Shift-Cmd-K) → delete ios/build + DerivedData → rm -rf ios/Pods → bundle exec pod install → npx react-native start --reset-cache. Script phase fails with “Sandbox: rsync deny” → ENABLE_USER_SCRIPT_SANDBOXING = NO(unverified). Xcode 27 fails pods whose deployment target is < 15.0 — raise it in post_install(unverified).

Traps

  • Opening App.xcodeproj: no Pods → “file not found”.
  • Metro reload after adding a native lib: needs pods + rebuild.
  • Hand-editing ios/ in Expo CNG: prebuild overwrites it.
  • Permission asked from JS, no Info.plist key → crash.

Remember

Workspace, not project · pod install after native change · plist, entitlements, manifest, signing.

Report a problem ·Discuss this folio