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
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 installresolves every native dep’s podspec, runs Codegen, writesPods.xcodeproj+ the workspace. Any native dep change, RN upgrade orPodfileedit ⇒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=0builds 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(canOpenURLlist),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:prebuildoverwrites it. - Permission asked from JS, no Info.plist key → crash.