Integration With Existing Apps Ios

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';

Key Concepts

The keys to integrating React Native components into your iOS application are to:

Set up the correct directory structure.
Install the necessary NPM dependencies.
Adding React Native to your Podfile configuration.
Writing the TypeScript code for your first React Native screen.
Integrate React Native with your iOS code using a RCTRootView.
Testing your integration by running the bundler and seeing your app in action.

Using the Community Template

While you follow this guide, we suggest you to use the React Native Community Template as reference. The template contains a minimal iOS app and will help you understanding how to integrate React Native into an existing iOS app.

Prerequisites

Follow the guide on setting up your development environment and using React Native without a framework to configure your development environment for building React Native apps for iOS. This guide also assumes you're familiar with the basics of iOS development such as creating a UIViewController and editing the Podfile file.

1. Set up directory structure

To ensure a smooth experience, create a new folder for your integrated React Native project, then move your existing iOS project to the /ios subfolder.

2. Install NPM dependencies

Go to the root directory and run the following command:

shell

curl -O https://raw.githubusercontent.com/react-native-community/template/refs/heads/0.77-stable/template/package.json

This will copy the package.json file from the Community template to your project.

Next, install the NPM packages by running:

shell

npm install

</TabItem> <TabItem value="yarn">

shell

yarn install

</TabItem> </Tabs>

Installation process has created a new node_modules folder. This folder stores all the JavaScript dependencies required to build your project.

Add node_modules/ to your .gitignore file (here the Community default one).

3. Install Development tools

Command Line Tools for Xcode

Install the Command Line Tools. Choose Settings... (or Preferences...) in the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

CocoaPods

CocoaPods is a package management tool for iOS and macOS development. We use it to add the actual React Native framework code locally into your current project.

We recommend installing CocoaPods using Homebrew:

shell

brew install cocoapods

4. Adding React Native to your app

Configuring CocoaPods

To configure CocoaPods, we need two files:

A Gemfile that defines which Ruby dependencies we need.
A Podfile that defines how to properly install our dependencies.

For the Gemfile, go to the root directory of your project and run this command

curl -O https://raw.githubusercontent.com/react-native-community/template/refs/heads/0.77-stable/template/Gemfile

This will download the Gemfile from the template. Similarly, for the Podfile, go to the ios folder of your project and run

curl -O https://raw.githubusercontent.com/react-native-community/template/refs/heads/0.77-stable/template/ios/Podfile

Please use the Community Template as a reference point for the Gemfile and for the Podfile.

:::note Remember to change this line and this line of the Podfile to match the name of your app.

If your app don't have tests, remember to remove this block. :::

Now, we need to run a couple of extra commands to install the Ruby gems and the Pods. Navigate to the ios folder and run the following commands:

bundle install
bundle exec pod install

The first command will install the Ruby dependencies and the second command will actually integrate the React Native code in your application so that your iOS files can import the React Native headers.

5. Writing the TypeScript Code

Now we will actually modify the native iOS application to integrate React Native.

The first bit of code we will write is the actual React Native code for the new screen that will be integrated into our application.

Create a `index.js` file

First, create an empty index.js file in the root of your React Native project.

index.js is the starting point for React Native applications, and it is always required. It can be a small file that imports other file that are part of your React Native component or application, or it can contain all the code that is needed for it.

Our index.js should look as follows (here the Community template file as reference):

import {AppRegistry} from 'react-native';
import App from './App';

AppRegistry.registerComponent('HelloWorld', () => App);

Create a `App.tsx` file

Let's create an App.tsx file. This is a TypeScript file that can have JSX expressions. It contains the root React Native component that we will integrate into our iOS application (link):

tsx

import React from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  Text,
  useColorScheme,
  View,
} from 'react-native';

import {
  Colors,
  DebugInstructions,
  Header,
  ReloadInstructions,
} from 'react-native/Libraries/NewAppScreen';

function App(): React.JSX.Element {
  const isDarkMode = useColorScheme() === 'dark';

  const backgroundStyle = {
    backgroundColor: isDarkMode ? Colors.darker : Colors.lighter,
  };

  return (
    <SafeAreaView style={backgroundStyle}>
      <StatusBar
        barStyle={isDarkMode ? 'light-content' : 'dark-content'}
        backgroundColor={backgroundStyle.backgroundColor}
      />
      <ScrollView
        contentInsetAdjustmentBehavior="automatic"
        style={backgroundStyle}>
        <Header />
        <View
          style={{
            backgroundColor: isDarkMode
              ? Colors.black
              : Colors.white,
            padding: 24,
          }}>
          <Text style={styles.title}>Step One</Text>
          <Text>
            Edit <Text style={styles.bold}>App.tsx</Text> to
            change this screen and see your edits.
          </Text>
          <Text style={styles.title}>See your changes</Text>
          <ReloadInstructions />
          <Text style={styles.title}>Debug</Text>
          <DebugInstructions />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  title: {
    fontSize: 24,
    fontWeight: '600',
  },
  bold: {
    fontWeight: '700',
  },
});

export default App;

Here the Community template file as reference

5. Integrating with your iOS code

We now need to add some native code in order to start the React Native runtime and tell it to render our React components.

Requirements

React Native is supposed to work with the AppDelegate. The following part assumes that your AppDelegate looks like this:

objc

#import "AppDelegate.h"
#import "ViewController.h"

@interface AppDelegate ()

@end

@implementation AppDelegate {
  UIWindow *window;
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  window = [UIWindow new];
  window.rootViewController = [ViewController new];
  [window makeKeyAndVisible];
  return YES;
}

@end

</TabItem> <TabItem value="swift">

swift

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    window = UIWindow()
    window?.rootViewController = ViewController()
    window?.makeKeyAndVisible()
    return true
  }
}

</TabItem> </Tabs>

Update the `AppDelegate` class

First, we need to extends the AppDelegate to inherit from one of the classes provided by React Native: RCTAppDelegate.

To achieve this, we have to modify the AppDelegate.h file and the AppDelegate.m files:

Open the AppDelegate.h files and modify it as it follows (See the official template's AppDelegate.h as reference):

diff

#import <UIKit/UIKit.h>
+#import <React-RCTAppDelegate/RCTAppDelegate.h>

-@interface AppDelegate : UIResponder <UIApplicationDelegate>
+@interface AppDelegate : RCTAppDelegate


@end

Open the AppDelegate.mm file and modify it as it follows (See the official template's AppDelegate.mm as reference

diff

#import "AppDelegate.h"
#import "ViewController.h"
+#import <React/RCTBundleURLProvider.h>

@interface AppDelegate ()

@end

@implementation AppDelegate {
  UIWindow *window;
}

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+ self.automaticallyLoadReactNativeWindow = NO;
+ return [super application:application didFinishLaunchingWithOptions:launchOptions];
   window = [UIWindow new];
   window.rootViewController = [ViewController new];
   [window makeKeyAndVisible];
   return YES;

 }

+- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
+{
+  return [self bundleURL];
+}

+- (NSURL *)bundleURL
+{
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+#endif
+}
 @end

Let's have a look at the code above:

We are inheriting from the RCTAppDelegate and we are calling the application:didFinishLaunchingWithOptions of the RCTAppDelegate. This delegates all the React Native initialization processes to the base class.
We are customizing the RCTAppDelegate by setting the automaticallyLoadReactNativeWindow to NO. This step instruct React Native that the app is handling the UIWindow and React Native should not worry about that.
The methods sourceURLForBridge: and bundleURL are used by the App to tell to React Native where it can find the JS bundle that needs to be rendered. The sourceURLForBridge: is from the Old Architecture and you can see that it is deferring the decision to the bundleURL method, required by the New Architecture.

</TabItem> <TabItem value="swift">

To achieve this, we have to modify the AppDelegate.swift

Open the AppDelegate.swift files and modify it as it follows (See the official template's AppDelegate.swift as reference):

diff

import UIKit
+import React_RCTAppDelegate

@main
-class AppDelegate: UIResponder, UIApplicationDelegate {
+class AppDelegate: RCTAppDelegate {

-  var window: UIWindow?

-  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+  override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
+    self.automaticallyLoadReactNativeWindow = false
+    super.application(application, didFinishLaunchingWithOptions: launchOptions)
    window = UIWindow()
-    window?.rootViewController = ViewController()
-    window?.makeKeyAndVisible()
+    window.rootViewController = ViewController()
+    window.makeKeyAndVisible()
    return true
  }

+  override func sourceURL(for bridge: RCTBridge) -> URL? {
+    self.bundleURL()
+  }

+  override func bundleURL() -> URL? {
+#if DEBUG
+    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+#else
+    Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+#endif
+  }
}

Let's have a look at the code above:

We are inheriting from the RCTAppDelegate and we are calling the application(_:didFinishLaunchingWithOptions:) of the RCTAppDelegate. This delegates all the React Native initialization processes to the base class.
We are customizing the RCTAppDelegate by setting the automaticallyLoadReactNativeWindow to false. This step instruct React Native that the app is handling the UIWindow and React Native should not worry about that.
The methods sourceURLForBridge(for:) and bundleURL() are used by the App to tell to React Native where it can find the JS bundle that needs to be rendered. The sourceURLForBridge(for:) is from the Old Architecture and you can see that it is deferring the decision to the bundleURL() method, required by the New Architecture.

</TabItem> </Tabs>

Presenting a React Native view in a rootViewController

Finally, we can present our React Native view. To do so, we need a new View Controller that can host a view in which we can load the JS content.

From Xcode, let's create a new UIViewController (Let's call it ReactViewController).
Have the Initial ViewController present the ReactViewController. There are several ways to do so, depending on your app. For this example, we assume that you have a button that presents React Native Modally.

diff

#import "ViewController.h"
+#import "ReactViewController.h"

@interface ViewController ()

@end

- @implementation ViewController
+@implementation ViewController {
+  ReactViewController *reactViewController;
+}

 - (void)viewDidLoad {
   [super viewDidLoad];
   // Do any additional setup after loading the view.
   self.view.backgroundColor = UIColor.systemBackgroundColor;
+  UIButton *button = [UIButton new];
+  [button setTitle:@"Open React Native" forState:UIControlStateNormal];
+  [button setTitleColor:UIColor.systemBlueColor forState:UIControlStateNormal];
+  [button setTitleColor:UIColor.blueColor forState:UIControlStateHighlighted];
+  [button addTarget:self action:@selector(presentReactNative) forControlEvents:UIControlEventTouchUpInside];
+  [self.view addSubview:button];

+  button.translatesAutoresizingMaskIntoConstraints = NO;
+  [NSLayoutConstraint activateConstraints:@[
+    [button.leadingAnchor constraintEqualToAnchor:self.view.leadingAnchor],
+    [button.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor],
+    [button.centerYAnchor constraintEqualToAnchor:self.view.centerYAnchor],
+    [button.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+  ]];
 }

+- (void)presentReactNative
+{
+  if (reactViewController == NULL) {
+    reactViewController = [ReactViewController new];
+  }
+  [self presentViewController:reactViewController animated:YES completion:nil];
+}

@end

</TabItem> <TabItem value="swift">

diff

import UIKit

class ViewController: UIViewController {

+  var reactViewController: ReactViewController?

  override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view.
    self.view.backgroundColor = .systemBackground

+    let button = UIButton()
+    button.setTitle("Open React Native", for: .normal)
+    button.setTitleColor(.systemBlue, for: .normal)
+    button.setTitleColor(.blue, for: .highlighted)
+    button.addAction(UIAction { [weak self] _ in
+      guard let self else { return }
+      if reactViewController == nil {
+       reactViewController = ReactViewController()
+      }
+      present(reactViewController!, animated: true)
+    }, for: .touchUpInside)
+    self.view.addSubview(button)
+
+    button.translatesAutoresizingMaskIntoConstraints = false
+    NSLayoutConstraint.activate([
+      button.leadingAnchor.constraint(equalTo: self.view.leadingAnchor),
+      button.trailingAnchor.constraint(equalTo: self.view.trailingAnchor),
+      button.centerXAnchor.constraint(equalTo: self.view.centerXAnchor),
+      button.centerYAnchor.constraint(equalTo: self.view.centerYAnchor),
+    ])
  }
}

</TabItem> </Tabs>

Update the ReactViewController code as it follows:

diff

#import "ReactViewController.h"
+#import <React-RCTAppDelegate/RCTRootViewFactory.h>
+#import <React-RCTAppDelegate/RCTAppDelegate.h>

@interface ReactViewController ()

@end

@implementation ReactViewController

 - (void)viewDidLoad {
   [super viewDidLoad];
   // Do any additional setup after loading the view.
+   RCTRootViewFactory *factory = ((RCTAppDelegate *)RCTSharedApplication().delegate).rootViewFactory;
+   self.view = [factory viewWithModuleName:@"HelloWorld"];
 }

@end

</TabItem> <TabItem value="swift">

diff

import UIKit
+import React_RCTAppDelegate

class ReactViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

+    let factory = (RCTSharedApplication()?.delegate as? RCTAppDelegate)?.rootViewFactory
+    self.view = factory?.view(withModuleName: "HelloWorld")
  }
}

</TabItem> </Tabs>

Make sure to disable the Sandbox scripting. To achieve this, in Xcode, click on your app, then on build settings. Filter for script and set the User Script Sandboxing to NO. This step is needed to properly switch between the Debug and Release version of the Hermes engine that we ship with React Native.

;

6. Test your integration

You have completed all the basic steps to integrate React Native with your application. Now we will start the Metro bundler to build your TypeScript application code into a bundle. Metro's HTTP server shares the bundle from localhost on your developer environment to a simulator or device. This allows for hot reloading.

First, you need to create a metro.config.js file in the root of your project as follows:

const {getDefaultConfig} = require('@react-native/metro-config');
module.exports = getDefaultConfig(__dirname);

You can checkout the metro.config.js file from the Community template file as reference.

Once you have the config file in place, you can run the bundler. Run the following command in the root directory of your project:

shell

npm start

</TabItem> <TabItem value="yarn">

shell

yarn start

</TabItem> </Tabs>

Now build and run your iOS app as normal.

Once you reach your React-powered Activity inside the app, it should load the JavaScript code from the development server and display:

Creating a release build in Xcode

You can use Xcode to create your release builds too! The only additional step is to add a script that is executed when the app is built to package your JS and images into the iOS application.

In Xcode, select your application
Click on Build Phases
Click on the + in the top left corner and select New Run Script Phase
Click on the Run Script line and rename the Script to Bundle React Native code and images
Paste in the text box the following script

set -e

WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"

Drag and drop the script before the one called [CP] Embed Pods Frameworks.

Now, if you build your app for Release, it will work as expected.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Key Concepts

Using the Community Template

Prerequisites

1. Set up directory structure

2. Install NPM dependencies

3. Install Development tools

Command Line Tools for Xcode

CocoaPods

4. Adding React Native to your app

Configuring CocoaPods

5. Writing the TypeScript Code

Create a index.js file

Create a App.tsx file

5. Integrating with your iOS code

Requirements

Update the AppDelegate class

Presenting a React Native view in a rootViewController

6. Test your integration

Creating a release build in Xcode

Now what?

Create a `index.js` file

Create a `App.tsx` file

Update the `AppDelegate` class