Skip to main content

​
iOS Development Setup

Set up your development environment to build and run React Native applications on iOS devices and simulators.

​
Prerequisites

Before you begin, ensure you have:
  • macOS computer (required for iOS development)
  • Node.js (^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0)
  • Xcode 14 or newer
  • CocoaPods or use built-in CocoaPods
  • Command Line Tools for Xcode

​
Installing Xcode

1

Download Xcode

Install Xcode from the Mac App Store or Apple Developer Downloads.
2

Install Command Line Tools

Open Terminal and run:
xcode-select --install
3

Accept Xcode License

sudo xcodebuild -license accept

​
Installing CocoaPods

CocoaPods manages iOS dependencies for React Native: 
sudo gem install cocoapods
Or use Homebrew: 
brew install cocoapods

​
Podfile Configuration

Your ios/Podfile defines the native dependencies: 
require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, min_ios_version_supported
prepare_react_native_project!

target 'YourApp' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    :hermes_enabled => flags[:hermes_enabled],
    :fabric_enabled => flags[:fabric_enabled],
    :new_arch_enabled => flags[:new_arch_enabled]
  )

  target 'YourAppTests' do
    inherit! :complete
  end

  post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false
    )
  end
end

​
React-Core Podspec

The main React Native pod is defined in React-Core.podspec. Key configurations: 
Pod::Spec.new do |s|
  s.name                   = "React-Core"
  s.version                = version
  s.summary                = "The core of React Native."
  s.homepage               = "https://reactnative.dev/"
  s.license                = package["license"]
  s.author                 = "Meta Platforms, Inc. and its affiliates"
  s.platforms              = min_supported_versions
  s.compiler_flags         = js_engine_flags()
  
  s.pod_target_xcconfig    = {
    "HEADER_SEARCH_PATHS" => header_search_paths,
    "DEFINES_MODULE" => "YES",
    "GCC_PREPROCESSOR_DEFINITIONS" => "RCT_METRO_PORT=${RCT_METRO_PORT}",
    "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard()
  }
  
  s.dependency "React-cxxreact"
  s.dependency "React-perflogger"
  s.dependency "React-jsi"
  s.dependency "React-jsiexecutor"
  s.dependency "React-runtimescheduler"
  s.dependency "Yoga"
  
  if use_hermes()
    s.dependency "React-hermes"
  end
end

​
AppDelegate Setup

Implement RCTAppDelegate in your AppDelegate: 
#import "AppDelegate.h"
#import <React/RCTAppDelegate.h>
#import <React/RCTBundleURLProvider.h>

@interface AppDelegate () <RCTAppDelegate>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.moduleName = @"YourApp";
    self.initialProps = @{};
    
    return [super application:application 
        didFinishLaunchingWithOptions:launchOptions];
}

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
    return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
}

- (BOOL)concurrentRootEnabled
{
    return true;
}

@end

​
Installing Dependencies

1

Navigate to iOS directory

cd ios
2

Install Pods

pod install
This reads your Podfile and installs all native dependencies.
3

Return to root directory

cd ..

​
Running on iOS

1

Start Metro bundler

npx react-native start
2

Run on simulator

npx react-native run-ios
Or specify a device:
npx react-native run-ios --simulator="iPhone 15 Pro"

​
Building for Physical Device

1

Open Xcode project

open ios/YourApp.xcworkspace
2

Select your device

In Xcode, select your connected device from the device dropdown.
3

Configure signing

  • Go to Signing & Capabilities
  • Select your development team
  • Xcode will automatically create a provisioning profile
4

Build and run

Click the Run button or press Cmd + R.

​
Common iOS Issues

​
Pod Install Fails

If pod install fails, try: 
cd ios
pod deintegrate
pod cache clean --all
pod install

​
Module Not Found

Clear the build folder: 
cd ios
xcodebuild clean
rm -rf ~/Library/Developer/Xcode/DerivedData

​
Metro Bundler Issues

Reset Metro cache: 
npx react-native start --reset-cache

​
Xcode Build Settings

Key build settings for React Native projects:
  • Deployment Target: iOS 13.4 or higher
  • Swift Language Version: Swift 5.0+
  • C++ Language Dialect: C++20
  • Bitcode: Disabled (required for React Native)

​
Framework Search Paths

Ensure your framework search paths include: 
$(PODS_CONFIGURATION_BUILD_DIR)/React-Core
$(PODS_CONFIGURATION_BUILD_DIR)/React-hermes
$(PODS_ROOT)/Headers/Public/FlipperKit

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us