Prerequisites for Applications
This documentation is still experimental and details are subject to changes as we iterate. Feel free to share your feedback on the discussion inside the working group for this page.
Moreover, it contains several manual steps. Please note that this won't be representative of the final developer experience once the New Architecture is stable. We're working on tools, templates and libraries to help you get started fast on the New Architecture, without having to go through the whole setup.
There are a few prerequisites that should be addressed before the New Architecture is enabled in your application.
Update to the latest React Native versionβ
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.
You can find instructions on how to upgrade in the page upgrading to new versions.
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 can use the JavaScript debugger in Flipper to directly debug your JavaScript code.
Please follow the instructions on the Hermes page to learn how to enable/disable Hermes.
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.
iOS - Build the Projectβ
After upgrading the project, there are a few changes you need to apply:
- Target the proper iOS version. Open the
Podfile
and apply this change:
- platform :ios, '11.0'
+ platform :ios, '12.4'
- Create a
.xcode.env
file to export the location of the NODE_BINARY. Navigate to theios
folder and run this command:
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 also supports 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.
- Fix an API change in the
AppDelegate.m
. Open this file and apply this change:
#if DEBUG
- return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index" fallbackResource:nil];
+ return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
iOS - Use Objective-C++ (.mm
extension)β
Turbo Native Modules can be written using Objective-C or C++. In order to support both cases, any source files in the user project space 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.
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.
For example, if you use the template, your project structure for what concerns iOS should look like this:
AppName
βββ ...
βββ ios
β βββ Podfile
β βββ Podfile.lock
β βββ Pods
β β βββ ...
β βββ AppName
β β βββ AppDelegate.h
β β βββ AppDelegate.mm
β β βββ Images.xcassets
β β βββ Info.plist
β β βββ LaunchScreen.storyboard
β β βββ main.m
β βββ AppName.xcodeproj
β βββ AppName.xcworkspace
β βββ AppNameTests
β βββ build
βββ ...
All the .m
files within the AppName
inner folder should be renamed from .m
to .mm
. If you have packages that contains Objective-C code at the same level of the AppName
folder, they should be renamed from .m
to .mm
too.
iOS - Make your AppDelegate conform to RCTAppDelegate
β
The final step to configure iOS for the New Architecture is to extend a base class provided by React Native, called RCTAppDelegate
.
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.
- Open the
ios/<AppName>/AppDelegate.h
file and update it as it follows:
- #import <React/RCTBridgeDelegate.h>
+ #import <RCTAppDelegate.h>
#import <UIKit/UIKit.h>
- @interface AppDelegate : UIResponder <UIApplicationDelegate, RCTBridgeDelegate>
+ @interface AppDelegate : RCTAppDelegate
- @property (nonatomic, strong) UIWindow *window;
@end
- Open the
ios/<AppName>/AppDelegate.mm
(remember that you have to rename theAppDelegate.m
toAppDelegate.mm
first) file and replace its content with the following:
#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
The moduleName
has to be the same string used in the [RCTRootView initWithBridge:moduleName:initialProperties]
call in the original AppDelegate.mm
file.
iOS - Run pod installβ
// Run pod install with the flags
RCT_NEW_ARCH_ENABLED=1 pod install
Android - Prerequisitesβ
If you successfully updated your project to React Native 0.71.0
, you already meet all the prerequisites to use the New Architecture on Android.
You will only need to update your android/gradle.properties
file as follows:
# Use this property to enable support to the new architecture.
# This will allow you to use TurboModules and the Fabric render in
# your application. You should enable this flag either if you want
# to write custom TurboModules/Fabric components OR use libraries that
# are providing them.
-newArchEnabled=false
+newArchEnabled=true
That's it!
Itβs now time to run your Android app to verify that everything works correctly:
yarn react-native run-android
In your Metro terminal log, you will now see the following log to confirm that Fabric is running correctly:
BUNDLE ./App.js
LOG Running "App" with {"fabric":true,"initialProps":{"concurrentRoot": "true"},"rootTag":1}