Skip to content

Commit

Permalink
[New Architecture][iOS][0.71.0] Update the App Migration section
Browse files Browse the repository at this point in the history
  • Loading branch information
Riccardo Cipolleschi committed Aug 17, 2022
1 parent 1cb8694 commit 6fdd57a
Show file tree
Hide file tree
Showing 8 changed files with 116 additions and 365 deletions.
203 changes: 113 additions & 90 deletions docs/new-architecture-app-intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ There are a few prerequisites that should be addressed before the New Architectu

React Native released the support for the New Architecture with the release `0.68.0`.

This guide is written with the expectation that you’re using the latest React Native release. At the moment of writing, this is `0.70.0`. Other than this guide, you can leverage the [upgrade helper](https://react-native-community.github.io/upgrade-helper/) to determine what other changes may be required for your project.
This guide is written with the expectation that you’re using the latest React Native release. At the moment of writing, this is `0.71.0`. Other than this guide, you can leverage the [upgrade helper](https://react-native-community.github.io/upgrade-helper/) to determine what other changes may be required for your project.

To update to the most recent version of React Native, you can run this command:

```bash
yarn add react-native@0.70.0
yarn add react-native@0.71.0
```

Starting from React Native `0.69.0`, you may also need to update the version of React to 18. You can do so by using this command:
Expand All @@ -27,7 +27,59 @@ Starting from React Native `0.69.0`, you may also need to update the version of
yarn add react@18.0.0
```

### Android specifics
## Use Hermes

Hermes is an open-source JavaScript engine optimized for React Native. Hermes is enabled by default and you have to explicitly disable it if you want to use JSC.

We highly recommend using Hermes in your application. With Hermes enabled, you will be able to use the JavaScript debugger in Flipper to directly debug your JavaScript code.

Please [follow the instructions on the React Native website](hermes) to learn how to enable/disable Hermes.

:::caution

**iOS:** If you opt out of using Hermes, you will need to replace `HermesExecutorFactory` with `JSCExecutorFactory` in any examples used throughout the rest of this guide.

:::

### Android

To enable Hermes in Android, open the `android/app/build.gradle` and apply the following changes:

```diff
project.ext.react = [
- enableHermes: true, // clean and rebuild if changing
+ enableHermes: true, // clean and rebuild if changing
]
// ...

}

if (enableHermes) {
- def hermesPath = "../../node_modules/hermes-engine/android/";
- debugImplementation files(hermesPath + "hermes-debug.aar")
- releaseImplementation files(hermesPath + "hermes-release.aar")
+ //noinspection GradleDynamicVersion
+ implementation("com.facebook.react:hermes-engine:+") { // From node_modules
+ exclude group:'com.facebook.fbjni'
+ }
} else {
```

Moreover, you'll need to update the `proguard-rules`, adding the following ones:

```
-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }
```

After that, remember to cleanup the project, running

```sh
cd android
./gradlew clean
```

## Android - Update Build System

Using the New Architecture on Android has some prerequisites that you need to meet:

Expand Down Expand Up @@ -149,63 +201,27 @@ dependencies {
+ implementation project(":ReactAndroid") // From node_modules
```

## Use Hermes

Hermes is an open-source JavaScript engine optimized for React Native. Hermes is enabled by default and you have to explicitly disable it if you want to use JSC.

We highly recommend using Hermes in your application. With Hermes enabled, you will be able to use the JavaScript debugger in Flipper to directly debug your JavaScript code.

Please [follow the instructions on the React Native website](hermes) to learn how to enable/disable Hermes.

:::caution
## iOS - Make the project build

**iOS:** If you opt out of using Hermes, you will need to replace `HermesExecutorFactory` with `JSCExecutorFactory` in any examples used throughout the rest of this guide.

:::

### Android
After upgrading the project, there are a few changes you need to apply:

To enable Hermes in Android, open the `android/app/build.gradle` and apply the following changes:
1. Target the proper iOS version. Open the `Podfile` and apply this change:

```diff
project.ext.react = [
- enableHermes: true, // clean and rebuild if changing
+ enableHermes: true, // clean and rebuild if changing
]
// ...

}

if (enableHermes) {
- def hermesPath = "../../node_modules/hermes-engine/android/";
- debugImplementation files(hermesPath + "hermes-debug.aar")
- releaseImplementation files(hermesPath + "hermes-release.aar")
+ //noinspection GradleDynamicVersion
+ implementation("com.facebook.react:hermes-engine:+") { // From node_modules
+ exclude group:'com.facebook.fbjni'
+ }
} else {
```

Moreover, you'll need to update the `proguard-rules`, adding the following ones:

```
-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }
- platform :ios, '11.0'
+ platform :ios, '12.4'
```

After that, remember to cleanup the project, running
2. Create an `.xcode.env` file to export the locaion of the NODE_BINARY. Navigate to the `ios` folder and run this command:

```sh
cd android
./gradlew clean
echo 'export NODE_BINARY=$(command -v node)' > .xcode.env
```

## iOS: Make the project build

After upgrading the project, there are a few changes you need to apply:
If you need it, you can also open the file and replace the `$(command -v node)` with the path to the node executable.
React Native supports also a local version of this file `.xcode.env.local`. This file is not synced with the repository to let you customize your local setup, if it differs from the Continuous Integration or the team one.

1. Fix an API change in the `AppDelegate.m`. Open this file and apply this change:
2. Fix an API change in the `AppDelegate.m`. Open this file and apply this change:

```diff
#if DEBUG
Expand All @@ -214,67 +230,74 @@ After upgrading the project, there are a few changes you need to apply:
#else
```

2. Target the proper iOS version. Open the `Podfile` and apply this change:
## iOS - Use Objective-C++ (`.mm` extension)

```diff
- platform :ios, '11.0'
+ platform :ios, '12.4'
```
TurboModules can be written using Objective-C or C++. In order to support both cases, any source files that include C++ code should use the `.mm` file extension. This extension corresponds to Objective-C++, a language variant that allows for the use of a combination of C++ and Objective-C in source files.

3. Create an `.xcode.env` file to export the locaion of the NODE_BINARY. Navigate to the `ios` folder and run this command:
:::important

```sh
echo 'export NODE_BINARY=$(command -v node)' > .xcode.env
```

If you need it, you can also open the file and replace the `$(command -v node)` with the path to the node executable.
React Native supports also a local version of this file `.xcode.env.local`. This file is not synced with the repository to let you customize your local setup, if it differs from the Continuous Integration or the team one.
Use Xcode to rename existing files to ensure file references persist in your project. You might need to clean the build folder (_Project → Clean Build Folder_) before re-building the app. If the file is renamed outside of Xcode, you may need to click on the old `.m` file reference and Locate the new file.

## iOS: Use Objective-C++ (`.mm` extension)
:::

TurboModules can be written using Objective-C or C++. In order to support both cases, any source files that include C++ code should use the `.mm` file extension. This extension corresponds to Objective-C++, a language variant that allows for the use of a combination of C++ and Objective-C in source files.
## iOS - Make your AppDelegate conform to `RCTAppDelegate`

:::info
The final step to configure iOS for the New Architecture is to extend a base class proided by React Native, called `RCTAppDelegate`.

Use Xcode to rename existing files to ensure file references persist in your project. You might need to clean the build folder (_Project → Clean Build Folder_) before re-building the app. If the file is renamed outside of Xcode, you may need to click on the old `.m` file reference and Locate the new file.
This class provides a base implementation for all the required functionalities of the new architecture. If you need to customize some of them, you can override those methods, invoke `[super methodNameWith:parameters:];` collecting the returned value and customize the bits you need to customize.

:::
1. Open the `ios/AppDelegate.h` file and update it as it follows:

## iOS: TurboModules: Ensure your App Provides an `RCTCxxBridgeDelegate`
```diff
- #import <React/RCTBridgeDelegate.h>
+ #import <React-RCTAppDelegate/RCTAppDelegate.h>
#import <UIKit/UIKit.h>

In order to set up the TurboModule system, you will add some code to interact with the bridge in your AppDelegate. Before you start, go ahead and rename your AppDelegate file to use the `.mm` extension.
- @interface AppDelegate : UIResponder <UIApplicationDelegate, RCTBridgeDelegate>
+ @interface AppDelegate : RCTAppDelegate

Now you will have your AppDelegate conform to `RCTCxxBridgeDelegate`. Start by adding the following imports at the top of your AppDelegate file:
- @property (nonatomic, strong) UIWindow *window;

```objc
#import <reacthermes/HermesExecutorFactory.h>
#import <React/RCTCxxBridgeDelegate.h>
#import <React/RCTJSIExecutorRuntimeInstaller.h>
@end
```

Then, declare your app delegate as a `RCTCxxBridgeDelegate` provider:
2. Open the `ios/AppDelegate.mm` file and replace its content with the following:

```objc
@interface AppDelegate () <RCTCxxBridgeDelegate> {
// ...
#import "AppDelegate.h"
#import <React/RCTBundleURLProvider.h>

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

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

- (BOOL)concurrentRootEnabled
{
return true;
}

@end
```
To conform to the `RCTCxxBridgeDelegate` protocol, you will need to implement the `jsExecutorFactoryForBridge:` method. Typically, this is where you would return a `JSCExecutorFactory` or `HermesExecutorFactory`, and we will use it to install our TurboModules bindings later on.

You can implement the `jsExecutorFactoryForBridge:` method like this:
:::note
The module name has to be the same string used in the `[RCTRootView initWithBridge:moduleName:initialProperties]` call in the original `AppDelegate.mm` file.
:::
```objc
#pragma mark - RCTCxxBridgeDelegate
## iOS - Run pod install
- (std::unique_ptr<facebook::react::JSExecutorFactory>)jsExecutorFactoryForBridge:(RCTBridge *)bridge
{
return std::make_unique<facebook::react::HermesExecutorFactory>(facebook::react::RCTJSIExecutorRuntimeInstaller([bridge](facebook::jsi::Runtime &runtime) {
if (!bridge) {
return;
}
})
);
}
```bash
// Run pod install with the flags
USE_FABRIC=1 RCT_NEW_ARCH_ENABLED=1 pod install
```
Loading

0 comments on commit 6fdd57a

Please sign in to comment.