diff --git a/docs/_getting-started-linux-android.md b/docs/_getting-started-linux-android.md index 0f45f1bf05b..839c6882c65 100644 --- a/docs/_getting-started-linux-android.md +++ b/docs/_getting-started-linux-android.md @@ -1,3 +1,5 @@ +import RemoveGlobalCLI from './\_remove-global-cli.md'; + ## Installing dependencies You will need Node, the React Native command line interface, a JDK, and Android Studio. @@ -77,7 +79,7 @@ React Native has a built-in command line interface. Rather than install and mana

Creating a new application

-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using `npx`, which ships with Node.js. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_getting-started-macos-android.md b/docs/_getting-started-macos-android.md index 2d1d724a971..b5e1cdd134b 100644 --- a/docs/_getting-started-macos-android.md +++ b/docs/_getting-started-macos-android.md @@ -1,3 +1,5 @@ +import RemoveGlobalCLI from './\_remove-global-cli.md'; + ## Installing dependencies You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio. @@ -91,7 +93,7 @@ React Native has a built-in command line interface. Rather than install and mana

Creating a new application

-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using `npx`, which ships with Node.js. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_getting-started-macos-ios.md b/docs/_getting-started-macos-ios.md index 285f0fbb7eb..9860a4cc4ba 100644 --- a/docs/_getting-started-macos-ios.md +++ b/docs/_getting-started-macos-ios.md @@ -1,4 +1,4 @@ -import M1Cocoapods from './\_markdown-m1-cocoapods.mdx'; +import M1Cocoapods from './\_markdown-m1-cocoapods.mdx'; import RemoveGlobalCLI from './\_remove-global-cli.md'; ## Installing dependencies @@ -57,7 +57,7 @@ React Native has a built-in command line interface. Rather than install and mana ## Creating a new application -> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_getting-started-windows-android.md b/docs/_getting-started-windows-android.md index d284ff3a9a2..7aa2b03f1d0 100644 --- a/docs/_getting-started-windows-android.md +++ b/docs/_getting-started-windows-android.md @@ -1,3 +1,5 @@ +import RemoveGlobalCLI from './\_remove-global-cli.md'; +

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio. @@ -108,7 +110,7 @@ React Native has a built-in command line interface. Rather than install and mana

Creating a new application

-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using `npx`, which ships with Node.js. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_remove-global-cli.md b/docs/_remove-global-cli.md new file mode 100644 index 00000000000..08d0d9ba3c1 --- /dev/null +++ b/docs/_remove-global-cli.md @@ -0,0 +1,5 @@ +> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues: +> +> ```shell +> npm uninstall -g react-native-cli @react-native-community/cli +> ``` diff --git a/docs/build-speed.md b/docs/build-speed.md index 05d33a058e3..7cbcacb390c 100644 --- a/docs/build-speed.md +++ b/docs/build-speed.md @@ -44,7 +44,7 @@ $ ./gradlew :app:assembleDebug -PreactNativeArchitectures=x86,x86_64 This can be useful if you wish to build your Android App on a CI and use a matrix to parallelize the build of the different architectures. -If you wish, you can also override this value locally, using the `gradle.properties` file you have in the [top level folder](https://github.com/facebook/react-native/blob/19cf70266eb8ca151aa0cc46ac4c09cb987b2ceb/template/android/gradle.properties#L30-L33) of your project: +If you wish, you can also override this value locally, using the `gradle.properties` file you have in the [top-level folder](https://github.com/facebook/react-native/blob/19cf70266eb8ca151aa0cc46ac4c09cb987b2ceb/template/android/gradle.properties#L30-L33) of your project: ``` # Use this property to specify which architecture you want to build. diff --git a/docs/direct-manipulation.md b/docs/direct-manipulation.md index c336455116c..3a711b81c99 100644 --- a/docs/direct-manipulation.md +++ b/docs/direct-manipulation.md @@ -3,6 +3,10 @@ id: direct-manipulation title: Direct Manipulation --- +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' + + + It is sometimes necessary to make changes directly to a component without using state/props to trigger a re-render of the entire subtree. When using React in the browser for example, you sometimes need to directly modify a DOM node, and the same is true for views in mobile apps. `setNativeProps` is the React Native equivalent to setting properties directly on a DOM node. :::caution diff --git a/docs/intro-react-native-components.md b/docs/intro-react-native-components.md index 8896c39653c..00d22878aad 100644 --- a/docs/intro-react-native-components.md +++ b/docs/intro-react-native-components.md @@ -1,7 +1,7 @@ --- id: intro-react-native-components -title: Core Components and Native Components -description: 'React Native lets you compose app interfaces using Native Components. Conveniently, it comes with a set of these components for you to get started with right now—the Core Components!' +title: Core Components and Fabric Components +description: 'React Native lets you compose app interfaces using Fabric Components. Conveniently, it comes with a set of these components for you to get started with right now—the Core Components!' --- import ThemedImage from '@theme/ThemedImage'; @@ -17,13 +17,13 @@ In Android and iOS development, a **view** is the basic building block of UI: a
Just a sampling of the many views used in Android and iOS apps.
-## Native Components +## Fabric Components -In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components **Native Components.** +In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components **Fabric Components.** [_Fabric_](architecture/fabric-renderer) is the name of the React Native renderer, therefore components that are rendered via Fabric are called Fabric Components. -React Native comes with a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's **Core Components**. +React Native comes with a set of essential, ready-to-use Fabric Components you can use to start building your app today. These are React Native's **Core Components**. -React Native also lets you build your own Native Components for [Android](native-components-android.md) and [iOS](native-components-ios.md) to suit your app’s unique needs. We also have a thriving ecosystem of these **community-contributed components.** Check out [Native Directory](https://reactnative.directory) to find what the community has been creating. +React Native also lets you build your own [Fabric Components](the-new-architecture/pillars-fabric-components) to suit your app’s unique needs. We also have a thriving ecosystem of these **community-contributed components.** Check out [Native Directory](https://reactnative.directory) to find what the community has been creating. ## Core Components diff --git a/docs/introduction.md b/docs/introduction.md index f77b91adf9b..b57e6da77ae 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -8,7 +8,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import con

- Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more! + Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Fabric Components, React, and more!

@@ -136,4 +136,4 @@ Menu paths are written in bold and use carets to navigate submenus. Example: **A --- -Now that you know how this guide works, it's time to get to know the foundation of React Native: [Native Components](intro-react-native-components.md). +Now that you know how this guide works, it's time to get to know the foundation of React Native: [Fabric Components](the-new-architecture/pillars-fabric-components). diff --git a/docs/more-resources.md b/docs/more-resources.md index 4dee1a6f333..7e061a9ccb4 100644 --- a/docs/more-resources.md +++ b/docs/more-resources.md @@ -34,7 +34,7 @@ We recommend using the [VS Code](https://code.visualstudio.com/) code editor and Try out apps from the [Showcase](https://reactnative.dev/showcase) to see what React Native is capable of! Looking for something more hands on? Check out this [set of example apps on GitHub](https://github.com/ReactNativeNews/React-Native-Apps). You can look at their source code—try running one on a simulator or device. -## Find, make, and share your own Native Components and Modules +## Find, make, and share your own Native Components and TurboModules React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components! diff --git a/docs/native-components-android.md b/docs/native-components-android.md index 7c6d1722134..51b2e302678 100644 --- a/docs/native-components-android.md +++ b/docs/native-components-android.md @@ -4,6 +4,9 @@ title: Android Native UI Components --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' + + There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like `ScrollView` and `TextInput`, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, we can wrap up these existing components for seamless integration with your React Native application. diff --git a/docs/native-components-ios.md b/docs/native-components-ios.md index eea45ed1db2..bba1b3559f6 100644 --- a/docs/native-components-ios.md +++ b/docs/native-components-ios.md @@ -3,6 +3,10 @@ id: native-components-ios title: iOS Native UI Components --- +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' + + + There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like `ScrollView` and `TextInput`, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, we can wrap up these existing components for seamless integration with your React Native application. Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with iOS programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing `MapView` component available in the core React Native library. diff --git a/docs/native-modules-android.md b/docs/native-modules-android.md index 2ad60b60c4a..df5066d7e2c 100644 --- a/docs/native-modules-android.md +++ b/docs/native-modules-android.md @@ -3,8 +3,11 @@ id: native-modules-android title: Android Native Modules --- +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; + + Welcome to Native Modules for Android. Please start by reading the [Native Modules Intro](native-modules-intro) for an intro to what native modules are. ## Create a Calendar Native Module diff --git a/docs/native-modules-intro.md b/docs/native-modules-intro.md index 331419956d5..35162726dfa 100644 --- a/docs/native-modules-intro.md +++ b/docs/native-modules-intro.md @@ -3,6 +3,10 @@ id: native-modules-intro title: Native Modules Intro --- +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' + + + Sometimes a React Native app needs to access a native platform API that is not available by default in JavaScript, for example the native APIs to access Apple or Google Pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing. The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself! diff --git a/docs/native-modules-ios.md b/docs/native-modules-ios.md index ae27042c3eb..433acc37cd0 100644 --- a/docs/native-modules-ios.md +++ b/docs/native-modules-ios.md @@ -3,6 +3,10 @@ id: native-modules-ios title: iOS Native Modules --- +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' + + + Welcome to Native Modules for iOS. Please start by reading the [Native Modules Intro](native-modules-intro) for an intro to what native modules are. ## Create a Calendar Native Module diff --git a/docs/native-modules-setup.md b/docs/native-modules-setup.md index 75b67a41fd4..42b877394c0 100644 --- a/docs/native-modules-setup.md +++ b/docs/native-modules-setup.md @@ -3,6 +3,10 @@ id: native-modules-setup title: Native Modules NPM Package Setup --- +import NativeDeprecated from './the-new-architecture/\_markdown_native_deprecation.mdx' + + + Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find [this guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) useful. To get set up with the basic project structure for a native module we will use the community tool called [create-react-native-library](https://github.com/callstack/react-native-builder-bob). You can go ahead further and dive deep into how that library works, but for our needs we will only execute the basic script: diff --git a/docs/new-architecture-app-intro.md b/docs/new-architecture-app-intro.md index c04a00c7b87..dc7948d4dff 100644 --- a/docs/new-architecture-app-intro.md +++ b/docs/new-architecture-app-intro.md @@ -7,40 +7,29 @@ import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; -There’s a few prerequisites that should be addressed before the new architecture is enabled in your application. +There are a few prerequisites that should be addressed before the New Architecture is enabled in your application. -## Use a React Native nightly release +## Use a React Native >= 0.68 release -At this time, you must use a React Native nightly release in order to get access to the most up to date changes. Eventually, we will recommend targeting a minimum stable open source release. +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 a specific nightly release. As new revisions of this guide are released, the target nightly release may be updated. The specific nightly version that we will be using throughout the rest of this guide is version `0.0.0-20220201-2008-79975d146`. +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. -Before upgrading your app to a specific nightly release, we recommend upgrading your app to the latest open source release. By upgrading to a published open source release first, you will be able to take advantage of tools like the [upgrade helper](https://react-native-community.github.io/upgrade-helper/) to determine what other changes may be required for your project. - -As of this writing, the latest stable release is `0.67.2`. Once you have upgraded your project to this version successfully, you may proceed to targeting the `0.0.0-20220201-2008-79975d146` nightly release. You may target this nightly release the same way you’d target any other version of React Native: +To update to the most recent version of React Native, you can run this command: ```bash -yarn add react-native@0.0.0-20220201-2008-79975d146 +yarn add react-native@0.70.0 ``` -## Install react-native-codegen - -Make sure that you're using the latest version of the [`react-native-codegen`](https://www.npmjs.com/package/react-native-codegen) NPM package. At the time of writing it's `0.0.13`. +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: ```bash -yarn add react-native-codegen +yarn add react@18.0.0 ``` -:::info - -If you see an error like `***TypeError: RNCodegen.generateFromSchemas is not a function.***`, it means that you're using a older version of `react-native-codegen`. -Make sure you don't have an older version installed under the `node_modules/react-native/node_modules` folder. You can remove that or reinstall everything in node_modules to fix the problem. - -::: - ### Android specifics -Using the new architecture on Android has some prerequisites that you need to meet: +Using the New Architecture on Android has some prerequisites that you need to meet: 1. Using Gradle 7.x and Android Gradle Plugin 7.x 2. Using the **new React Gradle Plugin** @@ -49,40 +38,52 @@ Using the new architecture on Android has some prerequisites that you need to me You can update Gradle by running: ```bash -cd android && ./gradlew wrapper --gradle-version 7.3 --distribution-type=all +cd android && ./gradlew wrapper --gradle-version 7.3.3 --distribution-type=all ``` -While the AGP version should be updated inside the **top level** `build.gradle` file at the `com.android.tools.build:gradle` dependency line. - -If you’re set with it, let’s now install the new Gradle plugin which is distributed through a NPM package called [**`react-native-gradle-plugin`**](https://www.npmjs.com/package/react-native-gradle-plugin). You can do so with: - -```bash -yarn add react-native-gradle-plugin -``` +While the AGP version should be updated inside the **top-level** `build.gradle` file at the `com.android.tools.build:gradle` dependency line. -You can control if you have the package already installed by doing: - -```bash -ls -la node_modules/react-native-gradle-plugin -``` - -Now, you can edit your **top level** `settings.gradle` file to include the following line at the end of the file: +Now, you can edit your **top-level** `settings.gradle` file to include the following line at the end of the file: ```groovy includeBuild('../node_modules/react-native-gradle-plugin') include(":ReactAndroid") project(":ReactAndroid").projectDir = file('../node_modules/react-native/ReactAndroid') +include(":ReactAndroid:hermes-engine") +project(":ReactAndroid:hermes-engine").projectDir = file('../node_modules/react-native/ReactAndroid/hermes-engine') +``` + +Then, open the `android/app/src/main/AndroidManifest.xml` file and add this line: + +```diff +android:windowSoftInputMode="adjustResize" ++ android:exported="true"> + ``` Then, edit your **top-level Gradle file** to include the highlighted lines: ```groovy buildscript { + ext { + buildToolsVersion = "31.0.0" + minSdkVersion = 21 + compileSdkVersion = 31 + targetSdkVersion = 31 + if (System.properties['os.arch'] == "aarch64") { + // For M1 Users we need to use the NDK 24 which added support for aarch64 + ndkVersion = "24.0.8215888" + } else { + // Otherwise we default to the side-by-side NDK version from AGP. + ndkVersion = "21.4.7075529" + } + } + // ... dependencies { // Make sure that AGP is at least at version 7.x - classpath("com.android.tools.build:gradle:7.0.4") + classpath("com.android.tools.build:gradle:7.2.0") // Add those lines classpath("com.facebook.react:react-native-gradle-plugin") @@ -93,35 +94,68 @@ buildscript { Edit your **module-level** **Gradle file** (usually `app/build.gradle[.kts]`) to include the following: -```groovy +```diff +// ... + apply plugin: "com.android.application" -// Add those lines -apply plugin: "com.facebook.react" -// Add those lines as well -react { - reactRoot = rootProject.file("../node_modules/react-native/") - codegenDir = rootProject.file("../node_modules/react-native-codegen/") -} +// ... + +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 { + +// ... + ++ configurations.all { ++ resolutionStrategy.dependencySubstitution { ++ substitute(module("com.facebook.react:react-native")) ++ .using(project(":ReactAndroid")) ++ .because("On New Architecture we're building React Native from source") ++ substitute(module("com.facebook.react:hermes-engine")) ++ .using(project(":ReactAndroid:hermes-engine")) ++ .because("On New Architecture we're building Hermes from source") ++ } ++ } + +// Run this once to be able to run the application with BUCK +// puts all compile dependencies into folder libs for BUCK to use +task copyDownloadableDepsToLibs(type: Copy) { + +// ... + ++ def isNewArchitectureEnabled() { ++ // To opt-in for the New Architecture, you can either: ++ // - Set `newArchEnabled` to true inside the `gradle.properties` file ++ // - Invoke gradle with `-newArchEnabled=true` ++ // - Set an environment variable `ORG_GRADLE_PROJECT_newArchEnabled=true` ++ return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true" ++ } ``` Finally, it’s time to update your project to use the `react-native` dependency from source, rather than using a precompiled artifact from the NPM package. This is needed as the later setup will rely on building the native code from source. -Let’s edit your **module level** `build.gradle` (the one inside `app/` folder) and change the following line: +Let’s edit your **module-level** `build.gradle` (the one inside `app/` folder) and change the following line: -```groovy +```diff dependencies { - // Replace this: - implementation "com.facebook.react:react-native:+" // From node_modules - // With this: - implementation project(":ReactAndroid") // From node_modules +- implementation "com.facebook.react:react-native:+" // From node_modules ++ implementation project(":ReactAndroid") // From node_modules ``` ## Use Hermes -Hermes is an open-source JavaScript engine optimized for React Native. 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. +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) in order to enable Hermes in your application. +Please [follow the instructions on the React Native website](hermes) to learn how to enable/disable Hermes. :::caution @@ -129,29 +163,72 @@ Please [follow the instructions on the React Native website](hermes) in order to ::: -## iOS: Enable C++17 language feature support +### 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 +] +// ... + +} -Your Xcode project settings need to be updated to support C++17 language features. +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 { +``` -**Instructions** +Moreover, you'll need to update the `proguard-rules`, adding the following ones: -1. Select your project in the Project navigator on the left (e.g. MyXcodeApp) -2. Then, make sure your project is selected in the center pane (as opposed to a particular target in your project, e.g. MyXcodeApp under Project, not under Targets). -3. Go to Build Settings -4. Search for C++ Language Dialect or CLANG_CXX_LANGUAGE_STANDARD -5. Make sure **C++17** is selected from the dropdown menu (or enter "c++17" directly into the value box). +``` +-keep class com.facebook.hermes.unicode.** { *; } +-keep class com.facebook.jni.** { *; } +``` -If done correctly, your diff will show the following changes to your project file: +After that, remember to cleanup the project, running -```ruby -CLANG_CXX_LANGUAGE_STANDARD = "c++17" +```sh +cd android +./gradlew clean ``` -:::info +## iOS: Make the project build -Your project should also be configured to support Folly. This should be done automatically once the library dependency is picked up, so no further changes to your project are necessary. +After upgrading the project, there are a few changes you need to apply: -::: +1. Fix an API change in the `AppDelegate.m`. Open this file and apply this change: + +```diff +#if DEBUG +- return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index" fallbackResource:nil]; ++ return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"]; +#else +``` + +2. Target the proper iOS version. Open the `Podfile` and apply this change: + +```diff +- platform :ios, '11.0' ++ platform :ios, '12.4' +``` + +3. Create an `.xcode.env` file to export the locaion of the NODE_BINARY. Navigate to the `ios` folder and run this command: + +```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. ## iOS: Use Objective-C++ (`.mm` extension) @@ -201,14 +278,3 @@ You can implement the `jsExecutorFactoryForBridge:` method like this: ); } ``` - -## iOS: Setup Folly - -The previous step will incorporate in your iOS app a dependency called Folly. Folly requires some extra compiler flags to works properly. To set them up, follow these steps: - -1. In the **Project Navigator** (`cmd+1`), select your app project. -1. In the **Targets** section, select the target with the name of your app. -1. Select the **Build Settings** tab -1. Search for **Other C++ Flags** -1. Update the **Debug** configuration, adding following flags: `-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1` -1. Update the **Release** configuration with the following flags: `-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1` diff --git a/docs/new-architecture-app-modules-android.md b/docs/new-architecture-app-modules-android.md index 4891fd9690e..d6dd904f477 100644 --- a/docs/new-architecture-app-modules-android.md +++ b/docs/new-architecture-app-modules-android.md @@ -20,9 +20,9 @@ You can mitigate this by following the approach described in [Speeding up your B ::: -The code-gen will output some Java and some C++ code that now we need to build. +The Codegen will output some Java and some C++ code that now we need to build. -Let’s edit your **module level** `build.gradle` to include the **two** `externalNativeBuild` blocks detailed below inside the `android{}` block: +Let’s edit your **module-level** `build.gradle` to include the **two** `externalNativeBuild` blocks detailed below inside the `android{}` block: ```groovy android { @@ -39,10 +39,15 @@ android { "GENERATED_SRC_DIR=$buildDir/generated/source", "PROJECT_BUILD_DIR=$buildDir", "REACT_ANDROID_DIR=$rootDir/../node_modules/react-native/ReactAndroid", - "REACT_ANDROID_BUILD_DIR=$rootDir/../node_modules/react-native/ReactAndroid/build" + "REACT_ANDROID_BUILD_DIR=$rootDir/../node_modules/react-native/ReactAndroid/build", + "NODE_MODULES_DIR=$rootDir/../node_modules" cFlags "-Wall", "-Werror", "-fexceptions", "-frtti", "-DWITH_INSPECTOR=1" cppFlags "-std=c++17" targets "myapplication_appmodules" + // Fix for windows limit on number of character in file paths and in command lines + if (Os.isFamily(Os.FAMILY_WINDOWS)) { + arguments "NDK_APP_SHORT_COMMANDS=true" + } } } } @@ -89,42 +94,56 @@ Finally, we need to create a Makefile inside the `src/main/jni` folder called `A THIS_DIR := $(call my-dir) include $(REACT_ANDROID_DIR)/Android-prebuilt.mk -include $(GENERATED_SRC_DIR)/codegen/jni/Android.mk + +# If you wish to add a custom TurboModule or Fabric component in your app you +# will have to include the following autogenerated makefile. +# include $(GENERATED_SRC_DIR)/codegen/jni/Android.mk + +# Includes the MK file for autolinked libraries +include $(PROJECT_BUILD_DIR)/generated/rncli/src/main/jni/Android-rncli.mk include $(CLEAR_VARS) LOCAL_PATH := $(THIS_DIR) -LOCAL_MODULE := myapplication_appmodules - -LOCAL_C_INCLUDES := $(LOCAL_PATH) $(GENERATED_SRC_DIR)/codegen/jni -LOCAL_SRC_FILES := $(wildcard $(LOCAL_PATH)/*.cpp) $(wildcard $(GENERATED_SRC_DIR)/codegen/jni/*.cpp) -LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH) $(GENERATED_SRC_DIR)/codegen/jni - -# Please note as one of the library listed is libreact_codegen_samplelibrary -# This name will be generated as libreact_codegen_ -# where is the one you specified in the Gradle configuration -LOCAL_SHARED_LIBRARIES := libjsi \ - libfbjni \ - libglog \ - libfolly_json \ - libyoga \ - libreact_nativemodule_core \ - libturbomodulejsijni \ - librrc_view \ - libreact_render_core \ - libreact_render_graphics \ - libfabricjni \ - libfolly_futures \ - libreact_debug \ - libreact_render_componentregistry \ - libreact_render_debug \ - libruntimeexecutor \ - libreact_codegen_rncore \ - libreact_codegen_samplelibrary - -LOCAL_CFLAGS := \ - -DLOG_TAG=\"ReactNative\" -LOCAL_CFLAGS += -fexceptions -frtti -std=c++17 -Wall + +# You can customize the name of your application .so file here. +LOCAL_MODULE := awesomeapp_appmodules + +LOCAL_C_INCLUDES := $(LOCAL_PATH) $(PROJECT_BUILD_DIR)/generated/rncli/src/main/jni +LOCAL_SRC_FILES := $(wildcard $(LOCAL_PATH)/*.cpp) $(wildcard $(PROJECT_BUILD_DIR)/generated/rncli/src/main/jni/*.cpp) +LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH) $(PROJECT_BUILD_DIR)/generated/rncli/src/main/jni + +# If you wish to add a custom TurboModule or Fabric component in your app you +# will have to uncomment those lines to include the generated source +# files from the codegen (placed in $(GENERATED_SRC_DIR)/codegen/jni) +# +# LOCAL_C_INCLUDES += $(GENERATED_SRC_DIR)/codegen/jni +# LOCAL_SRC_FILES += $(wildcard $(GENERATED_SRC_DIR)/codegen/jni/*.cpp) +# LOCAL_EXPORT_C_INCLUDES += $(GENERATED_SRC_DIR)/codegen/jni + +# Here you should add any native library you wish to depend on. +LOCAL_SHARED_LIBRARIES := \ +libfabricjni \ +libfbjni \ +libfolly_runtime \ +libglog \ +libjsi \ +libreact_codegen_rncore \ +libreact_debug \ +libreact_nativemodule_core \ +libreact_render_componentregistry \ +libreact_render_core \ +libreact_render_debug \ +libreact_render_graphics \ +librrc_view \ +libruntimeexecutor \ +libturbomodulejsijni \ +libyoga + +# Autolinked libraries +LOCAL_SHARED_LIBRARIES += $(call import-codegen-modules) + +LOCAL_CFLAGS := -DLOG_TAG=\"ReactNative\" -fexceptions -frtti -std=c++17 include $(BUILD_SHARED_LIBRARY) ``` diff --git a/docs/new-architecture-app-renderer-ios.md b/docs/new-architecture-app-renderer-ios.md index 089fcaa8001..39f3226f55f 100644 --- a/docs/new-architecture-app-renderer-ios.md +++ b/docs/new-architecture-app-renderer-ios.md @@ -39,7 +39,7 @@ end ## 2. Update your root view -The way to render your app with Fabric depends on your setup. Here is an example of how you can enable Fabric in your app with the `RN_FABRIC_ENABLED` compiler flag to enable/disable. Refer [RN-Tester’s AppDelegate](https://github.com/facebook/react-native/blob/main/packages/rn-tester/RNTester/AppDelegate.mm) as an example. +How to render your app with Fabric depends on your setup. Here is an example of how you can enable Fabric in your app with the `RN_FABRIC_ENABLED` compiler flag to enable/disable. Refer [RN-Tester’s AppDelegate](https://github.com/facebook/react-native/blob/main/packages/rn-tester/RNTester/AppDelegate.mm) as an example. ```objc title="AppDelegate.mm" #ifdef RN_FABRIC_ENABLED diff --git a/docs/new-architecture-appendix.md b/docs/new-architecture-appendix.md index 1d6ef870ba1..56b3301423b 100644 --- a/docs/new-architecture-appendix.md +++ b/docs/new-architecture-appendix.md @@ -85,11 +85,31 @@ Callback functions are not type checked, and are generalized as `Object`s. You may also find it useful to refer to the JavaScript specifications for the core modules in React Native. These are located inside the `Libraries/` directory in the React Native repository. ::: -## II. Invoking the code-gen during development +## II. TypeScript to Native Type Mapping + +You may use the following table as a reference for which types are supported and what they map to in each platform: + +| TypeScript Type | Nullable Support? | Android (Java) | iOS | Note | +| ---------------------------------------------- | -------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `string` | string | null | `String` | `NSString` | | +| `boolean` | boolean | null | `Boolean` | `NSNumber` | | +| `Float`, `Double`, or `Int32` | No | `double` | `NSNumber` | | +| {| foo: string, ... |} | {| foo: string, ...|} | null | | | Object literal. This is recommended over simply using Object, for type safety. | +| `Object` | Object | null | `ReadableMap` | `@{} (untyped dictionary)` | Recommended to use object literal (see above). | +| `Array<*>` | Array<\*> | null | `ReadableArray` | `NSArray` (or `RCTConvertVecToArray` when used inside objects) | | +| `Function` | Function | null | | | | +| `Promise<*>` | Promise<\*> | null | `com.facebook.react.bridge.Promise` | `RCTPromiseResolve` and `RCTPromiseRejectBlock` | | +| Type aliases of the above | Yes | | | | +| Type Unions 'SUCCESS'|'FAIL' | Only as callbacks. | | | Type unions only supported as callbacks. | +| Callbacks: `( ) =>` | Yes | `com.facebook.react.bridge.Callback` | `RCTResponseSenderBlock` | Callback functions are not type checked, and are generalized as Objects. | + +You may also find it useful to refer to the JavaScript specifications for the core modules in React Native. These are located inside the `Libraries/` directory in the React Native repository. + +## III. Invoking the code-gen during development > This section contains information specific to v0.66 of React Native. -The code-gen is typically invoked at build time, but you may find it useful to generate your native interface code on demand for troubleshooting. +The Codegen is typically invoked at build time, but you may find it useful to generate your native interface code on demand for troubleshooting. If you wish to invoke the codegen manually, you have two options: @@ -98,7 +118,7 @@ If you wish to invoke the codegen manually, you have two options: ### Invoking a Gradle task directly -You can trigger the code-gen by invoking the following task: +You can trigger the Codegen by invoking the following task: ```bash ./gradlew generateCodegenArtifactsFromSchema --rerun-tasks @@ -140,12 +160,12 @@ node node_modules/react-native/scripts/generate-specs-cli.js \ [--libraryType all(default)|modules|components] ``` -> **NOTE:** The output artifacts of the code-gen are inside the build folder and should not be committed. +> **NOTE:** The output artifacts of the Codegen are inside the build folder and should not be committed. > They should be considered only for reference. ##### Example -The following is a basic example of invoking the code-gen script to generate native iOS interface code for a library that provides native modules. The JavaScript spec sources for this library are located in a `js/` subdirectory, and this library’s native code expects the native interfaces to be available in the `ios` subdirectory. +The following is a basic example of invoking the Codegen script to generate native iOS interface code for a library that provides native modules. The JavaScript spec sources for this library are located in a `js/` subdirectory, and this library’s native code expects the native interfaces to be available in the `ios` subdirectory. ```bash # Generate schema - only needs to be done whenever JS specs change @@ -162,7 +182,7 @@ node node_modules/react-native/scripts/generate-specs-cli.js \ In the above example, the code-gen script will generate several files: `MyLibSpecs.h` and `MyLibSpecs-generated.mm`, as well as a handful of `.h` and `.cpp` files, all located in the `ios` directory. -## III. Note on Existing Apps +## IV. Note on Existing Apps This guide provides instructions for migrating an application that is based on the default app template that is provided by React Native. If your app has deviated from the template, or you are working with an application that was never based off the template, then the following sections might help. diff --git a/docs/new-architecture-intro.md b/docs/new-architecture-intro.md index 58407601aa6..fa88aeb9e8d 100644 --- a/docs/new-architecture-intro.md +++ b/docs/new-architecture-intro.md @@ -1,6 +1,6 @@ --- id: new-architecture-intro -title: Adopting the New Architecture +title: Migrating to the New Architecture --- import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; diff --git a/docs/new-architecture-library-android.md b/docs/new-architecture-library-android.md index 51b6933deac..565546a12d0 100644 --- a/docs/new-architecture-library-android.md +++ b/docs/new-architecture-library-android.md @@ -7,41 +7,9 @@ import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; -Once you have defined the JavaScript specs for your native modules as part of the [prerequisites](new-architecture-library-intro) and followed the Android/Gradle setup, you are now ready to migrate your library to the new architecture. Here are the steps you can follow to accomplish this. +Once you have defined the JavaScript specs for your native modules as part of the [prerequisites](new-architecture-library-intro), setup the configuration of the Codegen, and followed the Android/Gradle setup, you are now ready to migrate your library to the new architecture. Here are the steps you can follow to accomplish this. -### 1. Configure Codegen in your Gradle File - -You can now configure Codegen by specifying the following in the module-level `build.gradle` file: - -```groovy -react { - libraryName = "samplelibrary" - codegenJavaPackageName = "com.example.samplelibrary" - root = rootProject.file("..") - jsRootDir = rootProject.file("../js/") - reactNativeDir = rootProject.file("../node_modules/react-native/") - codegenDir = rootProject.file("../node_modules/react-native-codegen/") -} -``` - -:::info - -Please note that this setup requires you to have the React Gradle Plugin configured in the prerequisite step). - -::: - -All the arguments are **optional** and provide **default values**, you might want to customize them to follow your setup. - -- `libraryName`: A string that identifies your library. By default, the codegen will use a library name that is derived from the name of the module with a `Spec` suffix. E.g. for `:example:project` it will be `ExampleProjectSpec`. -- `codegenJavaPackageName`: A string that represents the Java package your code should use. By default this will be `com.facebook.fbreact.specs` but you might want to customize it. -- `root`: Reference to the root of your project. By default is `..` as Gradle is running inside the `./android` folder. -- `reactNativeDir`: Reference to the `react-native` package root. Usually located inside `../node_modules/react-native`. For third-party NPM libraries that are installed in `node_modules`, this will be `../react-native`. -- `jsRootDir`: Reference to the directory that contains the JavaScript specs for this library. By default is `../js/`. -- `codegenDir`: Reference to the `react-native-codegen` root. Usually located inside `../node_modules/react-native-codegen`. - -The generator will write its output inside the **build folder**, specifically inside the `./build/generated/source/codegen` folder. - -## 2. Extend or implement the code-generated native interfaces +## 1. Extend or implement the code-generated native interfaces The JavaScript spec for your native module or component will be used to generate native interface code for each supported platform (i.e. Android and iOS). These native interface files will be generated **when a React Native application that depends on your library is built**. diff --git a/docs/new-architecture-library-intro.md b/docs/new-architecture-library-intro.md index 1c0eb9e14ac..fab1bbe4bb6 100644 --- a/docs/new-architecture-library-intro.md +++ b/docs/new-architecture-library-intro.md @@ -3,40 +3,36 @@ id: new-architecture-library-intro title: Prerequisites for Libraries --- -import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; +import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; The following steps will help ensure your modules and components are ready for the New Architecture. -## TurboModules: Define Specs in JavaScript - -Under the TurboModule system, the JavaScript spec will serve as the source of truth for the methods that are provided by each native module. Without the JavaScript spec, it is up to you to ensure your public method signatures are equivalent on Android and iOS. +## Define Specs in JavaScript -As the first step to adopting the new architecture, you will start by creating these specs for your native modules. You can do this, right now, prior to actually migrating your native module library to the new architecture. Your JavaScript spec will be used later on to generate native interface code for all the supported platforms, as a way to enforce uniform APIs across platforms. - -### Writing the JavaScript Spec - -The JavaScript spec defines all APIs that are provided by the native module, along with the types of those constants and functions. -Using a **typed** spec file allows us to be intentional and declare all the input arguments and outputs of your native module’s methods. +The JavaScript specs serve as the source of truth for the methods that are provided by each native module. They defines all APIs that are provided by the native module, along with the types of those constants and functions. +Using a **typed** spec file allows to be intentional and declare all the input arguments and outputs of your native module’s methods. :::info - -JavaScript spec files can be written in either [Flow](https://flow.org/) or [TypeScript](https://www.typescriptlang.org/). The Codegen process will automatically choose the correct type parser based on your spec file's extension (`.js` for Flow, `.ts` or `.tsx` for TypeScript). Note that TypeScript support is still in beta—if you come across any bugs or missing features, please [report them](https://github.com/reactwg/react-native-new-architecture/discussions/categories/q-a). - +Currently, this guide is written under the assumption that you will be using [Flow](https://flow.org/). The `react-native-codegen` package is also currently working only with Flow source as input. **TypeScript** support is in beta right now. ::: -#### TurboModules +To adopt the New Architecture, you start by creating these specs for your native modules and native components. You can do this prior to actually migrating to the New Architecture: the specs will be used later on to generate native interface code for all the supported platforms, as a way to enforce uniform APIs across platforms. + +#### Turbomodules -JavaScript spec files **must** be named `Native.js` (for TypeScript use extension `.ts` or `.tsx`) and they export a `TurboModuleRegistry` `Spec` object. The name convention is important because the Codegen process looks for modules whose spec file (either JavaScript of TypeScript) starts with the keyword `Native`. +JavaScript spec files **must** be named `Native.js` and they export a `TurboModuleRegistry` `Spec` object. The name convention is important because the Codegen process looks for modules whose `js` (`jsx`, `ts`, or `tsx`) spec file starts with the keyword `Native`. -The following snippets show a basic spec template, written in [Flow](https://flow.org/) as well as [TypeScript](https://www.typescriptlang.org/). +The following is a basic JavaScript spec template, written using the [Flow](https://flow.org/) syntax as well as [TypeScript](https://www.typescriptlang.org/). - - + + ```ts // @flow @@ -55,7 +51,7 @@ export default (TurboModuleRegistry.get(''): ?Spec); ``` - + ```ts import type { TurboModule } from 'react-native'; @@ -80,8 +76,10 @@ JavaScript spec files **must** be named `NativeComponent.js` ( The following snippet shows a basic JavaScript spec template, written in [Flow](https://flow.org/) as well as [TypeScript](https://www.typescriptlang.org/). - - + + ```ts // @flow strict-local @@ -101,7 +99,7 @@ export default (codegenNativeComponent( ``` - + ```ts import type { ViewProps } from 'ViewPropTypes'; @@ -124,9 +122,12 @@ export default codegenNativeComponent( When using Flow or TypeScript, you will be using [type annotations](https://flow.org/en/docs/types/) to define your spec. Keeping in mind that the goal of defining a JavaScript spec is to ensure the generated native interface code is type safe, the set of supported types will be those that can be mapped one-to-one to a corresponding type on the native platform. + + In general, this means you can use primitive types (strings, numbers, booleans), as well as function types, object types, and array types. Union types, on the other hand, are not supported. All types must be read-only. For Flow: either `+` or `$ReadOnly<>` or `{||}` objects. For TypeScript: `readonly` for properties, `Readonly<>` for objects, and `ReadonlyArray<>` for arrays. -> See Appendix [I. Flow Type to Native Type Mapping](./new-architecture-appendix#i-flow-type-to-native-type-mapping). (TypeScript to Native Type Mapping will be added soon.) +> See Appendix [I. Flow Type to Native Type Mapping](#i-flow-type-to-native-type-mapping). +> See Appendix [II. TypeScript to Native Type Mapping](#ii-typescript-to-native-type-mapping). ### Codegen helper types @@ -143,7 +144,7 @@ Later on those types are compiled to coresponding equivalents on target platform ### Be Consistent Across Platforms and Eliminate Type Ambiguity -Before adopting the new architecture in your native module, you will need to ensure your methods are consistent across platforms. This is something you will realize as you set out to write the JavaScript spec for your native module - remember, that JavaScript spec defines what the methods will look like on all supported platforms. +Before adopting the New Architecture in your native module, you will need to ensure your methods are consistent across platforms. This is something you will realize as you set out to write the JavaScript spec for your native module - remember, that JavaScript spec defines what the methods will look like on all supported platforms. If your existing native module has methods with the same name on multiple platforms, but with different numbers or types of arguments across platforms, you will need to find a way to make these consistent. If you have methods that can take two or more different types for the same argument, you will also need to find a way to resolve this type ambiguity as type unions are intentionally not supported. @@ -169,9 +170,22 @@ android/settings.gradle:apply from: file("../node_modules/@react-native-communit ... ``` +If you don't, open the `settings.gradle` file and add this line: + +```diff +rootProject.name = ++ apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings) +``` + +Then, open your `android/app/build.gradle` file and add this line at the end of the file: + +```kotlin +apply from: file("../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesAppBuildGradle(project) +``` + ### iOS -On iOS, this generally requires your library to provide a Podspec (see [`react-native-webview`](https://github.com/react-native-community/react-native-webview/blob/master/react-native-webview.podspec) for an example). +On iOS, make sure that your library provides a Podspec (see [`react-native-webview`](https://github.com/react-native-community/react-native-webview/blob/master/react-native-webview.podspec) for an example). :::info @@ -179,11 +193,38 @@ To determine if your library is set up for autolinking, check the CocoaPods outp ::: +## Configure Codegen + +[Codegen](the-new-architecture/pillars-codegen) is a tool that runs when you build an Android app or when you install the dependencies of an iOS app. It creates some scaffolding code that you won't have to create manually. + +Codegen can be configured in the `package.json` file of your Library. Add the following JSON object at the end of it. + +```diff + }, ++ "codegenConfig": { ++ "name": "", ++ "type": "all", ++ "jsSrcsDir": ".", ++ "android": { ++ "javaPackageName": "com.facebook.fbreact.specs" ++ } ++ } +} +``` + +- The `codegenConfig` is the key used by the Codegen to verify that there is some code to generate. +- The `name` field, is the name of the library. +- The `type` field is used to identify the type of module we want to create. Our suggestions is to keep `all` to support libraries that contains both TurboModule and Fabric Components. +- The `jsSrcsDir` is the directory where the codegen will start looking for JavaScript specs. +- The `android.javaPackageName` is the name of the package where the generated code wil end up. + +Android also requires to have the [React Gradle Plugin properly configured](new-architecture-app-intro#android-specifics) in your app. + ## Preparing your JavaScript codebase for the new React Native Renderer (Fabric) The new renderer also known as Fabric doesn’t use the UIManager so direct calls to UIManager will need to be migrated. Historically, calls to UIManager had some pretty complicated patterns. Fortunately, we’ve created new APIs that are much cleaner. These new APIs are forwards compatible with Fabric so you can migrate your code today and they will work properly when you turn on Fabric! -Fabric will be providing new type safe JS APIs that are much more ergonomic than some of the patterns we've seen in product code today. These APIs require references to the underlying component, no longer using the result of `findNodeHandle`. `findNodeHandle` is used to search the tree for a native component given a class instance. This was breaking the React abstraction model. `findNodeHandle` won’t be compatible with React 18 once we are ready to roll that out. Deprecation of `findNodeHandle` in React Native is similar to the [deprecation of `findDOMNode` in React DOM](https://reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage). +Fabric will be providing new type safe JS APIs that are much more ergonomic than some of the patterns we've seen in product code today. These APIs require references to the underlying component, no longer using the result of `findNodeHandle`. `findNodeHandle` is used to search the tree for a native component given a class instance. This was breaking the React abstraction model. `findNodeHandle` is not compatible with React 18. Deprecation of `findNodeHandle` in React Native is similar to the [deprecation of `findDOMNode` in React DOM](https://reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage). While we know that all deprecations are a hassle, this guide is intended to help people update components as smoothly as possible. Here are the steps you need to take to get your JS codebase ready for Fabric: @@ -437,7 +478,7 @@ Be wary of your assumptions as uncaught subtleties can introduce differences in ### Move the call to `requireNativeComponent` to a separate file -This will prepare for the JS to be ready for the new codegen system for the new architecture. The new file should be named `NativeComponent.js.` +This will prepare for the JS to be ready for the new codegen system for the New Architecture. The new file should be named `NativeComponent.js.` #### Old way diff --git a/docs/new-architecture-library-ios.md b/docs/new-architecture-library-ios.md index aa66a59613f..c5054bd6e8e 100644 --- a/docs/new-architecture-library-ios.md +++ b/docs/new-architecture-library-ios.md @@ -8,11 +8,11 @@ import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; -You have defined the JavaScript specs for your native modules as part of the [prerequisites](new-architecture-library-intro) and you are now ready to migrate your library to the new architecture. Here are the steps you can follow to accomplish this. +You have defined the JavaScript specs for your native modules as part of the [prerequisites](new-architecture-library-intro) and you are now ready to migrate your library to the New Architecture. Here are the steps you can follow to accomplish this. -## 1. Updating your Podspec for the new architecture +## 1. Updating your Podspec for the New Architecture -The new architecture makes use of CocoaPods. +The New Architecture makes use of CocoaPods. ### Add Folly and Other Dependencies @@ -21,9 +21,6 @@ We'll need to ensure Folly is configured properly in any projects that consume y Add these to your `Pod::Spec.new` block: ```ruby -# folly_version must match the version used in React Native -# See folly_version in react-native/React/FBReactNativeSpec/FBReactNativeSpec.podspec -folly_version = '2021.06.28.00-v2' folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32' Pod::Spec.new do |s| @@ -35,9 +32,9 @@ Pod::Spec.new do |s| } s.dependency "React-Core" - s.dependency "React-RCTFabric" # This is for fabric component + s.dependency "React-RCTFabric" # This is for Fabric Component s.dependency "React-Codegen" - s.dependency "RCT-Folly", folly_version + s.dependency "RCT-Folly" s.dependency "RCTRequired" s.dependency "RCTTypeSafety" s.dependency "ReactCommon/turbomodule/core" @@ -45,61 +42,28 @@ Pod::Spec.new do |s| end ``` -:::caution - -Currently, the Folly version used here must match the Folly version used by React Native. A version mismatch here may lead to errors when running `pod install`. If CocoaPods flags an issue with your Folly version, then you may have a version mismatch. Check which version is used by the core modules Podspecs (e.g. FBReactNativeSpec.podspec), and try running `pod install` again after editing your podspec with the correct Folly version. - - - -::: - -### Enable codegen in your `package.json` - -At this point, you are now ready to enable code-gen support in your library. In your library’s package.json add the following: - -:::info +## 2. Extend or implement the code-generated native interfaces -Please note that this format is subject to change. +The JavaScript spec for your native module or component will be used to generate native interface code for each supported platform (i.e. Android and iOS). These native interface files will be generated when a React Native application that depends on your library is built. -::: +While this generated native interface code **will not ship as part of your library**, you do need to make sure your Objective-C or Java code conforms to the protocols provided by these native interface files. You can use the Codegen script to generate your library’s native interface code in order to use **as reference**. -```json title="package.json" -"codegenConfig": { - "libraries": [ - { - "name": "YourTurboModuleSpec", - "type": "modules", - "jsSrcsDir": "Libraries" - }, - { - "name": "YourComponentName", - "type": "components", - "jsSrcsDir": "Libraries" - } - ] -} +```sh +cd +node node_modules/react_native/scripts/generate-artifacts.js \ + --path / \ + --outputPath \ ``` -There's three arguments that are required: - -- `name`: A name of your library. This will be used to determine import path for your library. -- `jsSrcsDir`: Path to the directory that contains the JavaScript specs for this library. - -These arguments are optional: - -- `type`: Optional. A string that determines which types of artifacts will be generated for your library: “modules” or “components”. If left unspecified, both modules and components artifacts will be generated. - -## 2. Extend or implement the code-generated native interfaces - -The JavaScript spec for your native module or component will be used to generate native interface code for each supported platform (i.e. Android and iOS). These native interface files will be generated when a React Native application that depends on your library is built. +This command will generate the boilerplate code required by iOS in the output path provided as paramenter. -While this generated native interface code will not ship as part of your library, you do need to make sure your Objective-C or Java code conforms to the protocols provided by these native interface files. You can use the code-gen script to generate your library’s native interface code in order to use as reference. The files that are output by the script should not be committed, but you’ll need to refer to them to determine what changes you need to make to your native modules in order for them to provide an implementation for each generated @protocol / native interface. +The files that are output by the script **should not be committed**, but you’ll need to refer to them to determine what changes you need to make to your native modules in order for them to provide an implementation for each generated `@protocol` / native interface. ### Conform to the protocols provided by the native interface code -Update your native module or component to ensure it implements/extends the native interface that has been code-generated from your JavaScript specs. +Update your native module or component to ensure it implements/extends the native interface that has been generated from your JavaScript specs. -Following the example set forth in the previous section, your library might import MyAwesomeSpecs.h, extend the relevant native interface, and implement the necessary methods for this interface: +Following the example set forth in the previous section, your library might import `MyAwesomeSpecs.h`, extend the relevant native interface, and implement the necessary methods for this interface: ```objc #import @@ -110,7 +74,7 @@ Following the example set forth in the previous section, your library might impo RCT_EXPORT_METHOD(getString:(NSString *)string callback:(RCTResponseSenderBlock)callback) { - // ... + // Implement this method } - (std::shared_ptr)getTurboModule:(const ObjCTurboModule::InitParams &)params @@ -119,4 +83,4 @@ RCT_EXPORT_METHOD(getString:(NSString *)string } ``` -For an existing native module, you will likely already have one or more instances of [`RCT_EXPORT_METHOD`](native-modules-ios#export-a-native-method-to-javascript). To migrate to the new architecture, you’ll need to make sure the method signature makes use of the structs provided by the codegen output. +For an existing native module, you will likely already have one or more instances of [`RCT_EXPORT_METHOD`](native-modules-ios#export-a-native-method-to-javascript). To migrate to the New Architecture, you’ll need to make sure the method signature makes use of the structs provided by the codegen output. diff --git a/docs/react-18-and-react-native.md b/docs/react-18-and-react-native.md index 6fe75cf445e..ed4a5d09eb6 100644 --- a/docs/react-18-and-react-native.md +++ b/docs/react-18-and-react-native.md @@ -4,6 +4,9 @@ title: React 18 & React Native --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; +import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx'; + + This page describes how to use React 18 with React Native using the React Native's New Architecture. diff --git a/docs/the-new-architecture/_markdown_beta_ts_support.mdx b/docs/the-new-architecture/_markdown_beta_ts_support.mdx new file mode 100644 index 00000000000..8ebff56f256 --- /dev/null +++ b/docs/the-new-architecture/_markdown_beta_ts_support.mdx @@ -0,0 +1,3 @@ +:::caution +The TypeScript support for the New Architecture is still in beta. +::: diff --git a/docs/the-new-architecture/_markdown_native_deprecation.mdx b/docs/the-new-architecture/_markdown_native_deprecation.mdx new file mode 100644 index 00000000000..569a078d147 --- /dev/null +++ b/docs/the-new-architecture/_markdown_native_deprecation.mdx @@ -0,0 +1,4 @@ +:::info +Native Module and Native Components are our stable technologies used by the legacy architecture. +They will be deprecated in the future when the New Architecture will be stable. The New Architecture uses [TurboModule](./the-new-architecture/pillars-turbomodules) and [Fabric Components](./the-new-architecture/pillars-fabric-components) to achieve similar results. +::: diff --git a/docs/the-new-architecture/backward-compatibility-fabric-components.md b/docs/the-new-architecture/backward-compatibility-fabric-components.md new file mode 100644 index 00000000000..8226a24730f --- /dev/null +++ b/docs/the-new-architecture/backward-compatibility-fabric-components.md @@ -0,0 +1,435 @@ +--- +id: backward-compatibility-fabric-components +title: Fabric Components as Native Components +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import constants from '@site/core/TabsConstants'; +import BetaTS from './\_markdown_beta_ts_support.mdx'; +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +:::info +The creation of a backward compatible Fabric Component requires the knowledge of how to create a Fabric Component. To recall these concepts, have a look at this [guide](pillars-fabric-components). + +Fabric Components only work when the New Architecture is properly setup. If you already have a library that you want to migrate to the New Architecture, have a look at the [migration guide](../new-architecture-intro) as well. +::: + +Creating a backward compatible Fabric Component lets your users continue leverage your library, independently from the architecture they use. The creation of such a component requires a few steps: + +1. Configure the library so that dependencies are prepared set up properly for both the Old and the New Architecture. +1. Update the codebase so that the New Architecture types are not compiled when not available. +1. Uniform the JavaScript API so that your user code won't need changes. + + + +While the last step is the same for all the platforms, the first two steps are different for iOS and Android. + +## Configure the Fabric Component Dependencies + +### iOS + +The Apple platform installs Fabric Components using [Cocoapods](https://cocoapods.org) as dependency manager. + +Every Fabric Component defines a `podspec` that looks like this: + +```ruby +require "json" + +package = JSON.parse(File.read(File.join(__dir__, "package.json"))) + +folly_version = '2021.07.22.00' +folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32' + +Pod::Spec.new do |s| + # Default fields for a valid podspec + s.name = "" + s.version = package["version"] + s.summary = package["description"] + s.description = package["description"] + s.homepage = package["homepage"] + s.license = package["license"] + s.platforms = { :ios => "11.0" } + s.author = package["author"] + s.source = { :git => package["repository"], :tag => "#{s.version}" } + + s.source_files = "ios/**/*.{h,m,mm,swift}" + # React Native Core dependency + s.dependency "React-Core" + + # The following lines are required by the New Architecture. + s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1" + s.pod_target_xcconfig = { + "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\"", + "OTHER_CPLUSPLUSFLAGS" => "-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1", + "CLANG_CXX_LANGUAGE_STANDARD" => "c++17" + } + + s.dependency "React-RCTFabric" + s.dependency "React-Codegen" + s.dependency "RCT-Folly", folly_version + s.dependency "RCTRequired" + s.dependency "RCTTypeSafety" + s.dependency "ReactCommon/turbomodule/core" +end +``` + +The **goal** is to avoid installing the dependencies when the app is prepared for the Old Architecture. + +When we want to install the dependencies, we use the following commands depending on the architecture: + +```sh +# For the Old Architecture, we use: +pod install + +# For the New Architecture, we use: +RCT_NEW_ARCH_ENABLED=1 pod install +``` + +Therefore, we can leverage this environment variable in the `podspec` to exclude the settings and the dependencies that are related to the New Architecture: + +```diff ++ if ENV['RCT_NEW_ARCH_ENABLED'] == '1' then + # The following lines are required by the New Architecture. + s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1" + # ... other dependencies ... + s.dependency "ReactCommon/turbomodule/core" ++ end +end +``` + +This `if` guard prevents the dependencies from being installed when the environment variable is not set. + +### Android + +To create a module that can work with both architectures, you need to configure Gradle to choose which files need to be compiled depending on the chosen architecture. This can be achieved by using **different source sets** in the Gradle configuration. + +:::note +Please note that this is currently the suggested approach. While it might lead to some code duplication, it will ensure the maximum compatibility with both architectures. You will see how to reduce the duplication in the next section. +::: + +To configure the Fabric Component so that it picks the proper sourceset, you have to update the `build.gradle` file in the following way: + +```diff title="build.gradle" ++// Add this function in case you don't have it already ++ def isNewArchitectureEnabled() { ++ return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true" ++} +// ... other parts of the build file +defaultConfig { + minSdkVersion safeExtGet('minSdkVersion', 21) + targetSdkVersion safeExtGet('targetSdkVersion', 31) ++ buildConfigField("boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()) ++ } ++ ++ sourceSets { ++ main { ++ if (isNewArchitectureEnabled()) { ++ java.srcDirs += ['src/newarch'] ++ } else { ++ java.srcDirs += ['src/oldarch'] ++ } ++ } + } +} +``` + +This changes do three main things: + +1. The first lines define a function that returns whether the New Architecture is enabled or not. +2. The `buildConfigField` line defines a build configuration boolean field called `IS_NEW_ARCHITECTURE_ENABLED`, and initialize it using the function declared in the first step. This allows you to check at runtime if a user has specified the `newArchEnabled` property or not. +3. The last lines leverage the function declared in step one to decide which source sets we need to build, depending on the choosen architecture. + +## Update the codebase + +### iOS + +The second step is to instruct Xcode to avoid compiling all the lines using the New Architecture types and files when we are building an app with the Old Architecture. + +A Fabric Component requires an header file and an implementation file to add the actual `View` to the module. + +For example, the `RNMyComponentView.h` header file could look like this: + +```objective-c +#import +#import + +#ifndef NativeComponentExampleComponentView_h +#define NativeComponentExampleComponentView_h + +NS_ASSUME_NONNULL_BEGIN + +@interface RNMyComponentView : RCTViewComponentView +@end + +NS_ASSUME_NONNULL_END + +#endif /* NativeComponentExampleComponentView_h */ +``` + +The implementation `RNMyComponentView.mm` file, instead, could look like this: + +```objective-c +#import "RNMyComponentView.h" + +// + +#import "RCTFabricComponentsPlugins.h" + +using namespace facebook::react; + +@interface RNMyComponentView () + +@end + +@implementation RNMyComponentView { + UIView * _view; +} + ++ (ComponentDescriptorProvider)componentDescriptorProvider +{ + // ... return the descriptor ... +} + +- (instancetype)initWithFrame:(CGRect)frame +{ + // ... initialize the object ... +} + +- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps +{ + // ... set up the props ... + + [super updateProps:props oldProps:oldProps]; +} + +Class MyComponentViewCls(void) +{ + return RNMyComponentView.class; +} + +@end +``` + +To make sure that Xcode skips these files, we can wrap **both** of them in some `#ifdef RCT_NEW_ARCH_ENABLED` compilation pragma. For example, the header file could change as follows: + +```diff ++ #ifdef RCT_NEW_ARCH_ENABLED +#import +#import + +// ... rest of the header file ... + +#endif /* NativeComponentExampleComponentView_h */ ++ #endif +``` + +The same two lines should be added in the implementation file, as first and last lines. + +The above snippet uses the same `RCT_NEW_ARCH_ENABLED` flag used in the previous [section](#dependencies-ios). When this flag is not set, Xcode skips the lines within the `#ifdef` during compilation and it does not include them into the compiled binary. The compiled binary will have a the `RNMyComponentView.o` object but it will be an empty object. + +### Android + +As we can't use conditional compilation blocks on Android, we will define two different source sets. This will allow to create a backward compatible TurboModule with the proper source that is loaded and compiled depending on the used architecture. + +Therefore, you have to: + +1. Create a Native Component in the `src/oldarch` path. See [this guide](../native-components-android) to learn how to create a Native Component. +2. Create a Fabric Component in the `src/newarch` path. See [this guide](pillars-fabric-components) to learn how to create a Fabric Component. + +and then instruct Gradle to decide which implementation to pick. + +Some files can be shared between a Native and a Fabric Component: these should be created or moved into a folder that is loaded by both the architectures. These files are: + +- the `.java` that instantiate and configure the Android View for both the components. +- the `ManagerImpl.java` file where which contains the logic of the ViewManager that can be shared between the Native and the Fabric Component. +- the `Package.java` file used to load the component. + +The final folder structure looks like this: + +```sh +my-component +├── android +│ ├── build.gradle +│ └── src +│ ├── main +│ │ ├── AndroidManifest.xml +│ │ └── java +│ │ └── com +│ │ └── MyComponent +│ │ ├── MyComponentView.java +│ │ ├── MyComponentViewManagerImpl.java +│ │ └── MyComponentViewPackage.java +│ ├── newarch +│ │ └── java +│ │ └── com +│ │ └── MyComponentViewManager.java +│ └── oldarch +│ └── java +│ └── com +│ └── MyComponentViewManager.java +├── ios +├── js +└── package.json +``` + +The code that should go in the `MyComponentViewManagerImpl.java` and that can be shared between the Native Component and the Fabric Component is, for example: + +```java title="example of MyComponentViewManager.java" +package com.MyComponent; +import androidx.annotation.Nullable; +import com.facebook.react.uimanager.ThemedReactContext; + +public class MyComponentViewManagerImpl { + + public static final String NAME = "MyComponent"; + + public static MyComponentView createViewInstance(ThemedReactContext context) { + return new MyComponentView(context); + } + + public static void setFoo(MyComponentView view, String param) { + // implement the logic of the foo function using the view and the param passed. + } +} +``` + +Then, the Native Component and the Fabric Component can be updated using the function declared in the shared manager. + +For example, for a Native Component: + +```java title="Native Component using the ViewManagerImpl" +public class MyComponentViewManager extends SimpleViewManager { + + ReactApplicationContext mCallerContext; + + public MyComponentViewManager(ReactApplicationContext reactContext) { + mCallerContext = reactContext; + } + + @Override + public String getName() { + // static NAME property from the shared implementation + return MyComponentViewManagerImpl.NAME; + } + + @Override + public MyComponentView createViewInstance(ThemedReactContext context) { + // static createViewInstance function from the shared implementation + return MyComponentViewManagerImpl.createViewInstance(context); + } + + @ReactProp(name = "foo") + public void setFoo(MyComponentView view, String param) { + // static custom function from the shared implementation + MyComponentViewManagerImpl.setFoo(view, param); + } + +} +``` + +And, for a Fabric Component: + +```java title="Fabric Component using the ViewManagerImpl" +// Use the static NAME property from the shared implementation +@ReactModule(name = MyComponentViewManagerImpl.NAME) +public class MyComponentViewManager extends SimpleViewManager + implements MyComponentViewManagerInterface { + + private final ViewManagerDelegate mDelegate; + + public MyComponentViewManager(ReactApplicationContext context) { + mDelegate = new MyComponentViewManagerDelegate<>(this); + } + + @Nullable + @Override + protected ViewManagerDelegate getDelegate() { + return mDelegate; + } + + @NonNull + @Override + public String getName() { + // static NAME property from the shared implementation + return MyComponentViewManagerImpl.NAME; + } + + @NonNull + @Override + protected MyComponentView createViewInstance(@NonNull ThemedReactContext context) { + // static createViewInstance function from the shared implementation + return MyComponentViewManagerImpl.createViewInstance(context); + } + + @Override + @ReactProp(name = "foo") + public void setFoo(MyComponentView view, @Nullable String param) { + // static custom function from the shared implementation + MyComponentViewManagerImpl.setFoo(view, param]); + } +} +``` + +For a step-by-step example on how to achieve this, have a look at [this repo](https://github.com/react-native-community/RNNewArchitectureLibraries/tree/feat/back-fabric-comp). + +## Unify the JavaScript specs + + + +The last step makes sure that the JavaScript behaves transparently to chosen architecture. + +For a Fabric Component, the source of truth is the `NativeComponent.js` (or `.ts`) spec file. The app accesses the spec file like this: + +```ts +import MyComponent from 'your-component/src/index'; +``` + +The **goal** is to conditionally `export` from the `index` file the proper object, given the architecture chosen by the user. We can achieve this with a code that looks like this: + + + + +```ts +// @flow +import { requireNativeComponent } from 'react-native'; + +const isFabricEnabled = global.nativeFabricUIManager != null; + +const myComponent = isFabricEnabled + ? require('./MyComponentNativeComponent').default + : requireNativeComponent('MyComponent'); + +export default myComponent; +``` + + + + +```ts +import requireNativeComponent from 'react-native/Libraries/ReactNative/requireNativeComponent'; + +const isFabricEnabled = global.nativeFabricUIManager != null; + +const myComponent = isFabricEnabled + ? require('./MyComponentNativeComponent').default + : requireNativeComponent('MyComponent'); + +export default myComponent; +``` + + + + +Whether you are using Flow or TypeScript for your specs, we understand which architecture is running by checking if the `global.nativeFabricUIManager` object has been set or not. + +:::caution +Please note that the New Architecture is still experimental. The `global.nativeFabricUIManager` API might change in the future for a function that encapsulate this check. +::: + +- If that object is `null`, the app has not enabled the Fabric feature. It's running on the Old Architecture, and the fallback is to use the default Native Components implementation ([iOS](../native-components-ios) or [Android](../native-components-android)). +- If that object is set, the app is running with Fabric enabled and it should use the `NativeComponent` spec to access the Fabric Component. diff --git a/docs/the-new-architecture/backward-compatibility-turbomodules.md b/docs/the-new-architecture/backward-compatibility-turbomodules.md new file mode 100644 index 00000000000..42d8a1cbc87 --- /dev/null +++ b/docs/the-new-architecture/backward-compatibility-turbomodules.md @@ -0,0 +1,370 @@ +--- +id: backward-compatibility-turbomodules +title: TurboModules as Native Modules +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import constants from '@site/core/TabsConstants'; +import BetaTS from './\_markdown_beta_ts_support.mdx'; +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +:::info +The creation of a backward compatible TurboModule requires the knowledge of how to create a TurboModule. To recall these concepts, have a look at this [guide](pillars-turbomodules). + +TurboModules only works when the New Architecture is properly setup. If you already have a library that you want to migrate to the New Architecture, have a look at the [migration guide](../new-architecture-intro) as well. +::: + +Creating a backward compatible TurboModule lets your users continue leverage your library, independently from the architecture they use. The creation of such a module requires a few steps: + +1. Configure the library so that dependencies are prepared set up properly for both the Old and the New Architecture. +1. Update the codebase so that the New Architecture types are not compiled when not available. +1. Uniform the JavaScript API so that your user code won't need changes. + + + +While the last step is the same for all the platforms, the first two steps are different for iOS and Android. + +## Configure the TurboModule Dependencies + +### iOS + +The Apple platform installs TurboModules using [Cocoapods](https://cocoapods.org) as dependency manager. + +Every TurboModule defines a `podspec` that looks like this: + +```ruby +require "json" + +package = JSON.parse(File.read(File.join(__dir__, "package.json"))) + +folly_version = '2021.07.22.00' +folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32' + +Pod::Spec.new do |s| + # Default fields for a valid podspec + s.name = "" + s.version = package["version"] + s.summary = package["description"] + s.description = package["description"] + s.homepage = package["homepage"] + s.license = package["license"] + s.platforms = { :ios => "11.0" } + s.author = package["author"] + s.source = { :git => package["repository"], :tag => "#{s.version}" } + + s.source_files = "ios/**/*.{h,m,mm,swift}" + # React Native Core dependency + s.dependency "React-Core" + + # The following lines are required by the New Architecture. + s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1" + s.pod_target_xcconfig = { + "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\"", + "CLANG_CXX_LANGUAGE_STANDARD" => "c++17" + } + + s.dependency "React-Codegen" + s.dependency "RCT-Folly", folly_version + s.dependency "RCTRequired" + s.dependency "RCTTypeSafety" + s.dependency "ReactCommon/turbomodule/core" + +end +``` + +The **goal** is to avoid installing the dependencies when the app is prepared for the Old Architecture. + +When we want to install the dependencies we use the following commands, depending on the architecture: + +```sh +# For the Old Architecture, we use: +pod install + +# For the New Architecture, we use: +RCT_NEW_ARCH_ENABLED=1 pod install +``` + +Therefore, we can leverage this environment variable in the `podspec` to exclude the settings and the dependencies that are related to the New Architecture: + +```diff ++ if ENV['RCT_NEW_ARCH_ENABLED'] == '1' then + # The following lines are required by the New Architecture. + s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1" + # ... other dependencies ... + s.dependency "ReactCommon/turbomodule/core" ++ end +end +``` + +This `if` guard prevents the dependencies from being installed when the environment variable is not set. + +### Android + +To create a module that can work with both architectures, you need to configure Gradle to choose which files need to be compiled depending on the chosen architecture. This can be achieved by using **different source sets** in the Gradle configuration. + +:::note +Please note that this is currently the suggested approach. While it might lead to some code duplication, it will ensure the maximum compatibility with both architectures. You will see how to reduce the duplication in the next section. +::: + +To configure the TurboModule so that it picks the proper sourceset, you have to update the `build.gradle` file in the following way: + +```diff title="build.gradle" ++// Add this function in case you don't have it already ++ def isNewArchitectureEnabled() { ++ return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true" ++} + + +// ... other parts of the build file + +defaultConfig { + minSdkVersion safeExtGet('minSdkVersion', 21) + targetSdkVersion safeExtGet('targetSdkVersion', 31) ++ buildConfigField("boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()) ++ } ++ ++ sourceSets { ++ main { ++ if (isNewArchitectureEnabled()) { ++ java.srcDirs += ['src/newarch'] ++ } else { ++ java.srcDirs += ['src/oldarch'] ++ } ++ } + } +} +``` + +This changes do three main things: + +1. The first lines define a function that returns whether the New Architecture is enabled or not. +2. The `buildConfigField` line defines a build configuration boolean field called `IS_NEW_ARCHITECTURE_ENABLED`, and initialize it using the function declared in the first step. This allows you to check at runtime if a user has specified the `newArchEnabled` property or not. +3. The last lines leverage the function declared in step one to decide which source sets we need to build, depending on the choosen architecture. + +## Update the codebase + +### iOS + +The second step is to instruct Xcode to avoid compiling all the lines using the New Architecture types and files when we are building an app with the Old Architecture. + +The file to change is the module implementation file, which is usually a `.mm` file. That file is structured as follow: + +- Some `#import` statements, among which there is a `.h` file. +- The module implementation, using the various `RCT_EXPORT_xxx` and `RCT_REMAP_xxx` macros. +- The `getTurboModule:` function, which uses the `` type, generated by The New Architecture. + +The **goal** is to make sure that the `TurboModule` still builds with the Old Architecture. To achieve that, we can wrap the `#import ".h"` and the `getTurboModule:` function into an `#ifdef RCT_NEW_ARCH_ENABLED` compilation directive, as shown in the following example: + +```diff +#import ".h" ++ #ifdef RCT_NEW_ARCH_ENABLED +#import ".h" ++ #endif + +// ... rest of your module + ++ #ifdef RCT_NEW_ARCH_ENABLED + - (std::shared_ptr)getTurboModule: + (const facebook::react::ObjCTurboModule::InitParams &)params + { + return std::make_shared>(params); + } ++ #endif + +@end +``` + +This snippet uses the same `RCT_NEW_ARCH_ENABLED` flag used in the previous [section](#dependencies-ios). When this flag is not set, Xcode skips the lines within the `#ifdef` during compilation and it does not include them into the compiled binary. + +### Android + +As we can't use conditional compilation blocks on Android, we will define two different source sets. This will allow to create a backward compatible TurboModule with the proper source that is loaded and compiled depending on the used architecture. + +Therefore, you have to: + +1. Create a Native Module in the `src/oldarch` path. See [this guide](../native-modules-intro) to learn how to create a Native Module. +2. Create a TurboModule in the `src/newarch` path. See [this guide](./pillars-turbomodules) to learn how to create a TurboModule + +and then instruct Gradle to decide which implementation to pick. + +Some files can be shared between a Native Module and a TurboModule: these should be created or moved into a folder that is loaded by both the architectures. These files are: + +- the `Package.java` file used to load the module. +- a `Impl.java` file where we can put the code that both the Native Module and the TurboModule has to execute. + +The final folder structure looks like this: + +```sh +my-module +├── android +│ ├── build.gradle +│ └── src +│ ├── main +│ │ ├── AndroidManifest.xml +│ │ └── java +│ │ └── com +│ │ └── MyModule +│ │ ├── MyModuleImpl.java +│ │ └── MyModulePackage.java +│ ├── newarch +│ │ └── java +│ │ └── com +│ │ └── MyModule.java +│ └── oldarch +│ └── java +│ └── com +│ └── MyModule.java +├── ios +├── js +└── package.json +``` + +The code that should go in the `MyModuleImpl.java` and that can be shared by the Native Module and the TurboModule is, for example: + +```java title="example of MyModuleImple.java" +package com.MyModule; + +import androidx.annotation.NonNull; +import com.facebook.react.bridge.Promise; +import java.util.Map; +import java.util.HashMap; + +public class MyModuleImpl { + + public static final String NAME = "MyModule"; + + public void foo(double a, double b, Promise promise) { + // implement the logic for foo and then invoke promise.resolve or + // promise.reject. + } +} +``` + +Then, the Native Module and the TurboModule can be updated with the following steps: + +1. Create a private instance of the `MyModuleImpl` class. +2. Initialize the instance in the module constructor. +3. Use the private instance in the modules methods. + +For example, for a Native Module: + +```java title="Native Module using the Impl module" +public class MyModule extends ReactContextBaseJavaModule { + + // declare an instance of the implementation + private MyModuleImpl implementation; + + CalculatorModule(ReactApplicationContext context) { + super(context); + // initialize the implementation of the module + implementation = MyModuleImpl(); + } + + @Override + public String getName() { + // NAME is a static variable, so we can access it using the class name. + return MyModuleImpl.NAME; + } + + @ReactMethod + public void foo(int a, int b, Promise promise) { + // Use the implementation instance to execute the function. + implementation.foo(a, b, promise); + } +} +``` + +And, for a TurboModule: + +```java title="TurboModule using the Impl module" +public class MyModule extends MyModuleSpec { + // declare an instance of the implementation + private MyModuleImpl implementation; + + CalculatorModule(ReactApplicationContext context) { + super(context); + // initialize the implementation of the module + implementation = MyModuleImpl(); + } + + @Override + @NonNull + public String getName() { + // NAME is a static variable, so we can access it using the class name. + return MyModuleImpl.NAME; + } + + @Override + public void foo(double a, double b, Promise promise) { + // Use the implementation instance to execute the function. + implementation.foo(a, b, promise); + } +} +``` + +For a step-by-step example on how to achieve this, have a look at [this repo](https://github.com/react-native-community/RNNewArchitectureLibraries/tree/feat/back-turbomodule). + +## Unify the JavaScript specs + + + +The last step makes sure that the JavaScript behaves transparently to chosen architecture. + +For a TurboModule, the source of truth is the `Native.js` (or `.ts`) spec file. The app accesses the spec file like this: + +```ts +import MyModule from 'your-module/src/index'; +``` + +The **goal** is to conditionally `export` from the `index` file the proper object, given the architecture chosen by the user. We can achieve this with a code that looks like this: + + + + +```ts +// @flow + +import { NativeModules } from 'react-native' + +const isTurboModuleEnabled = global.__turboModuleProxy != null; + +const myModule = isTurboModuleEnabled ? + require('./Native').default : + NativeModules.; + +export default myModule; +``` + + + + +```ts +const isTurboModuleEnabled = global.__turboModuleProxy != null; + +const myModule = isTurboModuleEnabled + ? require('./Native').default + : require('./').default; + +export default myModule; +``` + + + + +:::note +If you are using TypeScript and you want to follow the example, make sure to `export` the `NativeModule` in a separate `ts` file called `.ts`. +::: + +Whether you are using Flow or TypeScript for your specs, we understand which architecture is running by checking whether the `global.__turboModuleProxy` object has been set or not. + +:::caution +The `global.__turboModuleProxy` API may change in the future for a function that encapsulate this check. +::: + +- If that object is `null`, the app has not enabled the TurboModule feature. It's running on the Old Architecture, and the fallback is to use the default [`NativeModule` implementation](../native-modules-intro). +- If that object is set, the app is running with the TurboModules enabled and it should use the `Native` spec to access the TurboModule. diff --git a/docs/the-new-architecture/backward-compatibility.md b/docs/the-new-architecture/backward-compatibility.md new file mode 100644 index 00000000000..89c1f3ac73f --- /dev/null +++ b/docs/the-new-architecture/backward-compatibility.md @@ -0,0 +1,25 @@ +--- +id: backward-compatibility +title: What Backward Compatibility Is +--- + +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +Creating a backward compatible module is important to provide a library that works in both the **Old Architecture** and the **New Architecture**. Not all the users of your library will immediately jump on the New Architecture ship: it is a good thing that they will be able to use your library even if they are still using the old architecture. + +The trick to create a good backward compatible module is to minimize the changes required to adopt the new version. In that way, users of the module can smoothly move to the new version and migrate to the New Architecture when they are ready, ideally by issueing one different command. + +To achieve this result, we have to perform few changes in our **TurboModule** and **Fabric Component** configurations. The steps we have to follow are: + +1. **Update the installation configuration** to avoid using code that is not needed by the Old Architecture. +1. **Update the code** to support both architectures. Both Android and iOS build pipelines gives you mechanism to provide a library that will compile with the correct React Native Architecture. +1. **Configure the specs to load the proper implementation**, so that the JavaScript layer leverages the New Architecture whan it is available. + +:::info +The next sections requires that you are familiar with the [Pillars](pillars) of the **New Architecture**. +::: + +- To create a backward compatible **TurboModule**, follow [this guide](backward-compatibility-turbomodules). +- To create a backward compatible **Fabric Component**, follow [this guide](backward-compatibility-fabric-components). diff --git a/docs/the-new-architecture/landing-page.md b/docs/the-new-architecture/landing-page.md new file mode 100644 index 00000000000..403a1dee659 --- /dev/null +++ b/docs/the-new-architecture/landing-page.md @@ -0,0 +1,32 @@ +--- +id: landing-page +title: Introduction +--- + +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +Starting from version 0.68, React Native provides the New Architecture, which offers developers new capabilities for building highly performant and responsive apps. Visit [Why a New Architecture](why) to learn more about what drove the decision to re-architect, and the benefits it provides. + +In order to achieve these benefits, we had to rethink how Native Modules and Native Components work. This led us to develop the [Pillars of the New Architecture](pillars): + +- [TurboModules](pillars-turbomodules), a framework to support efficient and flexible integration with native code +- [Fabric renderer and components](pillars-fabric-components), which offer improved capabilities, cross-platform consistency, and performance in rendering +- [Codegen](pillars-codegen), which generates boilerplate C++ required by the New Architecture, via static typing in JavaScript + +## Get started with the New Architecture + +### For app developers + +To **create a new app** using the New Architecture, head over to [Creating a New Architecture App](use-app-template), which will get you up and running in a few quick steps with the new app template. + +To **migrate an existing app** to the New Architecture, follow [Adopting the New Architecture](../new-architecture-intro). + +### For library maintainers + +First, read up on the core concepts outlined in the [Pillars](pillars) section. + +Then, for a **how-to guide** on supporting the New Architecture, check out the [Migration](../new-architecture-library-intro) guide. + +For information on **supporting both the Old and New Architectures**, see the [Backwards Compatibility](backward-compatibility) guide. diff --git a/docs/the-new-architecture/pillars-codegen.md b/docs/the-new-architecture/pillars-codegen.md new file mode 100644 index 00000000000..f7510cff97f --- /dev/null +++ b/docs/the-new-architecture/pillars-codegen.md @@ -0,0 +1,231 @@ +--- +id: pillars-codegen +title: Codegen +--- + +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; + +The **Codegen** is not a proper pillar, but it is a tool that can be used to avoid writing of a lot of repetitive code. Using the **Codegen** is not mandatory: all the code that is generated by it can also be written manually. However, it generates scaffolding code that could save you a lot of time. + +The **Codegen** is invoked automatically by React Native every time an iOS or an Android app is built. Occasionally, you would like to run the scripts that generate the code manually to know which types and files are actually generated: this is a common scenario when developing [**TurboModules**](./pillars-turbomodules) and [**Fabric Components**](./pillars-fabric-components), for example. + +This guide teaches how to configure the **Codegen**, how to invoke it manually for each platform, and it describes the generated code. + +# Prerequisites + +You always need a React Native app to generate the code properly, even when invoking the **Codegen** manually. + +The **Codegen** process is tightly coupled with the build of the app and the scripts are located in the `react-native` NPM package. + +For the sake of this guide, create a project using the React Native CLI as follows: + +```sh +npx react-native init SampleApp --version 0.70.0 +``` + +:::note +This guide assumes that the React Native version in use is 0.70.0 or greater. +Previous versions of React Native uses a version of **Codegen** that requires a slightly different setup. +::: + +Then, add the module that requires the **Codegen** as an NPM dependency of the app: + +```sh +yarn add +``` + +See how to create a [TurboModule](pillars-turbomodules) or a [Fabric Component](pillars-fabric-components) to get more information on how to configure them. + +The rest of this guide assumes that you have a `TurboModule` and/or a `Fabric Component` properly set up. + +# iOS + +## Running the Codegen + +The **Codegen** for iOS relies on some Node scripts that are invoked during the build process. The scripts are located in the `MyApp/node_modules/react_native/scripts/` folder. + +The script that you have to run is the `generate-artifacts.js` script. This searches among all the dependencies of the app, looking for JS files which respects some specific conventions (look at [TurboModules](pillars-turbomodules) and [Fabric Components](pillars-fabric-components) sections for details) and it generates the required code. + +To invoke the script you can run this command from the root folder of your app: + +```sh +node node_modules/react_native/scripts/generate-artifacts.js \ + --path SampleApp/ \ + --outputPath \ +``` + +Given that the app has `TurboModules` and/or `Fabric Components` configured as a dependency, the **Codegen** will look for all of them and it will generate the code in the path you provided. + +## The Generated Code + +If you run the **Codegen** in your app with an output path of `codegen`, for example, you obtain the following structure: + +```title="iOS Codegen output" +codegen +└── build + └── generated + └── ios + ├── MyTurboModuleSpecs + │ ├── MyTurboModuleSpecs-generated.mm + │ └── MyTurboModuleSpecs.h + ├── FBReactNativeSpec + │ ├── FBReactNativeSpec-generated.mm + │ └── FBReactNativeSpec.h + ├── RCTThirdPartyFabricComponentsProvider.h + ├── RCTThirdPartyFabricComponentsProvider.mm + └── react + └── renderer + └── components + ├── MyFabricComponent + │ ├── ComponentDescriptors.h + │ ├── EventEmitters.cpp + │ ├── EventEmitters.h + │ ├── Props.cpp + │ ├── Props.h + │ ├── RCTComponentViewHelpers.h + │ ├── ShadowNodes.cpp + │ └── ShadowNodes.h + └── rncore + ├── ComponentDescriptors.h + ├── EventEmitters.cpp + ├── EventEmitters.h + ├── Props.cpp + ├── Props.h + ├── RCTComponentViewHelpers.h + ├── ShadowNodes.cpp + └── ShadowNodes.h +``` + +The `codegen` folder sits at the root of the hierarchy, as expected. Nested into it there are two more folders: `build/generated`. + +Then, there is an `ios` folder which contains: + +- A custom folder for each TurboModule. +- The header (`.h`) and implementation (`.mm`) files for the `RCTThirdPartyFabricComponentsProvider`. +- A base `react/renderer/components` folder which contains a custom folder for each `Fabric Component`. + +In the example above, there are both a TurboModule and a set of Fabric Components. These are generated by React Native itself: `FBReactNativeSpec` and `rncore`. These modules will always appear even if you don't have any extra TurboModule or Fabric Component: React Native requires them in order to work properly. + +### TurboModules + +Each TurboModule's folder contains two files: an interface file and an implementation file. + +The interface files have the same name of the TurboModule and they contain methods to initialize their the JSI interface. + +The implementation files, instead, have the `-generated` suffix and they contains the logic to invoke the native methods from JS and viceversa. + +### Fabric Components + +The content of each Fabric Component folder contains several files. The basic element for a Fabric Componenent is the `ShadowNode`: it represents a node in the React absract tree. The `ShadowNode` represents a React entity, therefore it could need some props, which are defined in the `Props` files and, sometimes, an `EventEmitter`, defined in the corresponding file. + +Additionally, the **Codegen** also creates a `ComponentDescriptor.h` and an `RCTComponentViewHelpers.h` files: the first one is used by React Native and Fabric to properly get a reference to the Component, while the latter contains some helper methods and protocols that can be implemented by the Native View to properly respond to JSI invocations. + +For further details about how Fabric works, have a look at the [Renderer](/architecture/fabric-renderer) section. + +### RCTThirdPartyFabricComponentsProvider + +These are an interface and an implementation files for a registry. React Native uses this registry at runtime to retrieve the right class for a required Fabric Component. Once React Native has an handle to that class, it can instantiate it. + +# Android + +## Running the Codegen + +Android `Codegen` relies on a Gradle task to generate the required code. First, you need to configure the Android app to work with the New Architecture, otherwise the Gradle task fails. + +1. Open the `MyApp/android/gradle.properties` file. +1. Flip the `newArchEnabled` flag from `false` to `true`. + +After that, you can navigate into the `SampleApp/android` folder and run: + +```sh +./gradlew generateCodegenArtifactsFromSchema +``` + +This tasks invokes the `generateCodegenArtifactsFromSchema` on all the the imported projects of the app (the app and all the node modules which are linked to it). It generates the code in the corresponding `node_modules/` folder. So, for example, if you have a Fabric Component whose node module is called `my-fabric-component`, the generated code is located in the `SampleApp/node_modules/my-fabric-component/android/build/generated/source/codegen` path. + +## The Generated Code + +Once the Gradle task completes, you can see different structures for a TurboModule or for a Fabric Component. The following tab shows how they appear: + + + + +```sh +codegen +├── java +│ └── com +│ └── MyTurbomodule +│ └── MyTurbomodule.java +├── jni +│ ├── Android.mk +│ ├── MyTurbomodule-generated.cpp +│ ├── MyTurbomodule.h +│ └── react +│ └── renderer +│ └── components +│ └── MyTurbomodule +│ ├── ComponentDescriptors.h +│ ├── EventEmitters.cpp +│ ├── EventEmitters.h +│ ├── Props.cpp +│ ├── Props.h +│ ├── ShadowNodes.cpp +│ └── ShadowNodes.h +└── schema.json +``` + + + + +```sh +codegen +├── java +│ └── com +│ └── facebook +│ └── react +│ └── viewmanagers +│ ├── MyFabricComponentManagerDelegate.java +│ └── MyFabricComponentManagerInterface.java +├── jni +│ ├── Android.mk +│ ├── CMakeLists.txt +│ ├── MyFabricComponent-generated.cpp +│ ├── MyFabricComponent.h +│ └── react +│ └── renderer +│ └── components +│ └── MyFabricComponent +│ ├── ComponentDescriptors.h +│ ├── EventEmitters.cpp +│ ├── EventEmitters.h +│ ├── Props.cpp +│ ├── Props.h +│ ├── ShadowNodes.cpp +│ └── ShadowNodes.h +└── schema.json +``` + + + + +Java can't interoperate seamlessly with C++ as Objective-C++ does. To work properly, the **Codegen** creates some bridging between the Java and the C++ world in the `jni` folder, where the Java Native Interfaces are defined. + +Notice that both TurboModules and Fabric Components comes with two build file descriptors: the `Android.mk` and the `CMakeLists.txt`. These are used by the Android app to actually build the external modules. + +### TurboModule + +The **Codegen** generates a Java abstract class in the `java` package which the same name of the TurboModule. This abstract class has to be implemented by the JNI C++ implementation. + +Then, it generates the C++ files in the `jni` folder. They follow the same iOS convention: there is an interface called `MyTurbomodule.h` and an implementation file called `MyTurbomodule-generated.cpp`. The former is an interface that allows React Natvie to initialize the JSI interface for the TurboModule. The latter is the implementation file which contains the logic to invoke the native method from JS and viceversa. + +### Fabric Component + +The **Codegen** for a Fabric Component contains a `MyFabricComponentManagerInterface.java` and a `MyFabricComponentManagerDelegate.java` in the `java` package. They are implemented and used by the native `MyFabricComponentManager` required to properly load the component at runtime (See the guide on how to create a [Fabric Component](./pillars-fabric-components) for details). + +Then, there is a layer of JNI C++ files that are used by Fabric to render the components. The basic element for a Fabric Componenent is the `ShadowNode`: it represents a node in the React absract tree. The `ShadowNode` represents a React entity, therefore it could need some props, which are defined in the `Props` files and, sometimes, an `EventEmitter`, defined in the corresponding file. + +The **Codegen** also creates a `ComponentDescriptor.h` which is required to get a proper handle to the Fabric Component. diff --git a/docs/the-new-architecture/pillars-fabric-components.md b/docs/the-new-architecture/pillars-fabric-components.md new file mode 100644 index 00000000000..03d7afc3082 --- /dev/null +++ b/docs/the-new-architecture/pillars-fabric-components.md @@ -0,0 +1,858 @@ +--- +id: pillars-fabric-components +title: Fabric Components +--- + +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; + +A Fabric Component is a UI component rendered on the screen using the [Fabric Renderer](https://reactnative.dev/architecture/fabric-renderer). Using Fabric Components instead of Native Components allows us to reap all the [benefits](./why) of the **New Architecture**: + +- Strongly typed interfaces that are consistent across platforms. +- The ability to write your code in C++, either exclusively or integrated with another native platform language, reducing the need to duplicate implementations across platforms. +- The use of JSI, a JavaScript interface for native code, which allows for more efficient communication between native and JavaScript code than the bridge. + +A Fabric Component is created starting from a **JavaScript specification**. Then [**Codegen**](./pillars-codegen) creates some C++ scaffolding code to connect the component-specific logic (for example, accessing some native platform capability) to the rest of the React Native infrastructure. The C++ code is the same for all the platforms. Once the component is properly connected with the scaffolding code, it is ready to be imported and used by an app. + +The following section guides you through the creation of a Fabric Component, step-by-step, targeting React Native 0.70.0. + +:::caution +Fabric Components only works with the **New Architecture** enabled. +To migrate to the **New Architecture**, follow the [Migration guide](../new-architecture-intro) +::: + +## How to Create a Fabric Components + +To create a Fabric Component, you have to follow these steps: + +1. Define a set of JavaScript specifications. +2. Configure the component so that **Codegen** can create the shared code and it can be added as a dependency for an app. +3. Write the required native code. + +Once these steps are done, the component is ready to be consumed by an app. The guide shows how to add it to an app, leveraging _autolinking_, and how to reference it from the JavaScript code. + +## 1. Folder Setup + +In order to keep the component decoupled from the app, it's a good idea to define the module separately from the app, and then add it as a dependency to your app later. This is also what you'll do for writing Fabric Component that can be released as open-source libraries later. + +For this guide, you are going to create a Fabric Component that centers some text on the screen. + +Create a new folder at the same level of the app and call it `RTNCenteredText`. + +In this folder, create three subfolders: `js`, `ios` and `android`. + +The final result should look like this: + +```sh +. +├── MyApp +└── RTNCenteredText + ├── android + ├── ios + └── js +``` + +## 2. JavaScript Specification + +The **New Architecture** requires interfaces specified in a typed dialect of JavaScript (either [Flow](https://flow.org/) or [TypeScript](https://www.typescriptlang.org/)). **Codegen** uses these specifications to generate code in strongly-typed languages, including C++, Objective-C++, and Java. + +There are two requirements the file containing this specification must meet: + +1. The file **must** be named `NativeComponent`, with a `.js` or `.jsx` extension when using Flow, or a `.ts`, or `.tsx` extension when using TypeScript. **Codegen** only looks for files matching this pattern. +2. The file must export a `HostComponent` object. + +Below are specifications of the `RTNCenteredText` component in both Flow and TypeScript. Create a `RTNCenteredText` file with the proper extension in the `js` folder. + + + + +```typescript +// @flow strict-local + +import type {ViewProps} from 'react-native/Libraries/Components/View/ViewPropTypes'; +import type {HostComponent} from 'react-native'; +import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent'; + +type NativeProps = $ReadOnly<{| + ...ViewProps, + text: ?string, + // add other props here +|}>; + +export default (codegenNativeComponent( + 'RTNCenteredText', +): HostComponent); +``` + + + + +```typescript +import type { ViewProps } from 'ViewPropTypes'; +import type { HostComponent } from 'react-native'; +import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent'; + +export interface NativeProps extends ViewProps { + ...ViewProps, + text: string | null | undefined, + // add other props here +} + +export default codegenNativeComponent( + 'RTNCenteredText' +) as HostComponent; +``` + + + + +At the beginning of the spec files, there are the imports. The most important imports, required by every Fabric Component, are: + +- The `HostComponent`: type the exported component needs to conform to. +- The `codegenNativeComponent` function: responsible to actually register the component in the JavaScript runtime. + +The second section of the files contains the **props** of the component. [Props](https://reactnative.dev/docs/next/intro-react#props) (short for "properties") are component-specific information that let you customize React components. In this case, you want to control the `text` property of the component. + +Finally, the spec file exports the returned value of the `codegenNativeComponent` generic function, invoked passing the name of the component. + +:::caution +The JavaScript files imports types from libraries, without setting up a proper node module and installing its dependencies. The outcome of this is that the IDE may have troubles resolving the import statements and it can output errors and warnings. +These will disappear as soon as the Fabric Component is added as a dependency of a React Native app. +::: + +## 3. Component Configuration + +Next, you need to add some configuration for [**Codegen**](pillars-codegen.md) and auto-linking. + +Some of these configuration files are shared between iOS and Android, while the others are platform-specific. + +### Shared + +The shared configuration is a `package.json` file that will be used by yarn when installing your module. Create the `package.json` file in the root of the `RTNCenteredText` directory. + +```json title="package.json" +{ + "name": "rtn-centered-text", + "version": "0.0.1", + "description": "Showcase a Fabric Component with a centered text", + "react-native": "js/index", + "source": "js/index", + "files": [ + "js", + "android", + "ios", + "rtn-centered-text.podspec", + "!android/build", + "!ios/build", + "!**/__tests__", + "!**/__fixtures__", + "!**/__mocks__" + ], + "keywords": ["react-native", "ios", "android"], + "repository": "https://github.com//rtn-centered-text", + "author": " (https://github.com/)", + "license": "MIT", + "bugs": { + "url": "https://github.com//rtn-centered-text/issues" + }, + "homepage": "https://github.com//rtn-centered-text#readme", + "devDependencies": {}, + "peerDependencies": { + "react": "*", + "react-native": "*" + }, + "codegenConfig": { + "name": "RTNCenteredTextSpecs", + "type": "components", + "jsSrcsDir": "js" + } +} +``` + +The upper part of the file contains some descriptive information like the name of the component, its version and its source files. Make sure to update the various placeholders which are wrapped in `<>`: replace all the occurrences of the ``, ``, and `` tokens. + +Then there are the dependencies for this package. For this guide, you need `react` and `react-native`. + +Finally, the **Codegen** configuration is specified by the `codegenConfig` field. It contains an array of libraries, each of which is defined by three other fields: + +- `name`: The name of the library. By convention, you should add the `Spec` suffix. +- `type`: The type of module contained by this package. In this case, it is a Fabric Component, thus the value to use is `components`. +- `jsSrcsDir`: the relative path to access the `js` specification that is parsed by **Codegen**. + +### iOS: Create the `.podspec` file + +For iOS, you'll need to create a `rtn-centered-text.podspec` file which will define the module as a dependency for your app. It will stay in the root of `RTNCenteredText`, alongside the `ios` folder. + +The file will look like this: + +```ruby title="rtn-centered-text.podspec" +require "json" + +package = JSON.parse(File.read(File.join(__dir__, "package.json"))) + +folly_version = '2021.07.22.00' +folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32' + +Pod::Spec.new do |s| + s.name = "rtn-centered-text" + s.version = package["version"] + s.summary = package["description"] + s.description = package["description"] + s.homepage = package["homepage"] + s.license = package["license"] + s.platforms = { :ios => "11.0" } + s.author = package["author"] + s.source = { :git => package["repository"], :tag => "#{s.version}" } + + s.source_files = "ios/**/*.{h,m,mm,swift}" + + s.dependency "React-Core" + + s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1" + s.pod_target_xcconfig = { + "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\"", + "OTHER_CPLUSPLUSFLAGS" => "-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1", + "CLANG_CXX_LANGUAGE_STANDARD" => "c++17" + } + + s.dependency "React-RCTFabric" + s.dependency "React-Codegen" + s.dependency "RCT-Folly", folly_version + s.dependency "RCTRequired" + s.dependency "RCTTypeSafety" + s.dependency "ReactCommon/turbomodule/core" +end +``` + +The `.podspec` file has to be a sibling of the `package.json` file and its name is the one we set in the `package.json`'s `name` property: `rtn-centered-text`. + +The first part of the file prepares some variables we will use throughout the rest of it. Then, there is a section that contains some information used to configure the pod, like its name, version, and description. Finally, we have a set of dependencies that are required by the New Architecture. + +### Android: `build.gradle`, `AndroidManifest.xml`, a `ReactPackage` class + +To prepare Android to run **Codegen** you have to create three files: + +1. The `build.gradle` with the **Codegen** configuration +1. The `AndroidManifest.xml` file +1. A java class that implements the `ReactPackage` interface. + +At the end of these steps, the `android` folder should look like this: + +```title="Android Folder Structure" +android +├── build.gradle +└── src + └── main + ├── AndroidManifest.xml + └── java + └── com + └── rtncenteredtext + └── RTNCenteredTextPackage.java +``` + +#### The `build.gradle` file + +First, create a `build.gradle` file in the `android` folder, with the following contents: + +```kotlin title="build.gradle" +buildscript { + ext.safeExtGet = {prop, fallback -> + rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback + } + repositories { + google() + gradlePluginPortal() + } + dependencies { + classpath("com.android.tools.build:gradle:7.1.1") + } +} + +apply plugin: 'com.android.library' +apply plugin: 'com.facebook.react' + +android { + compileSdkVersion safeExtGet('compileSdkVersion', 31) + + defaultConfig { + minSdkVersion safeExtGet('minSdkVersion', 21) + targetSdkVersion safeExtGet('targetSdkVersion', 31) + buildConfigField("boolean", "IS_NEW_ARCHITECTURE_ENABLED", "true") + } +} + +repositories { + maven { + // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm + url "$projectDir/../node_modules/react-native/android" + } + mavenCentral() + google() +} + +dependencies { + implementation 'com.facebook.react:react-native:+' +} +``` + +#### The `AndroidManifest.xml` + +Second, create an `android/src/main` folder. Inside that folder, create a `AndroidManifest.xml` file, with the following code: + +```xml title="AndroidManifest.xml" + + +``` + +This is a small manifest file that defines the package for your module. + +#### The `ReactPackage` class + +Finally, you need a class that implements the `ReactPackage` interface. To run the **Codegen** process, you don't have to completely implement the Package class: an empty implementation is enough for the app to pick up the module as a proper React Native dependency and to try and generate the scaffolding code. + +Create an `android/src/main/java/com/rtncenteredtext` folder and, inside that folder, create a `RTNCenteredTextPackage.java` file. + +```java title="RTNCenteredTextPackage" +package com.rtncenteredtext; + +import com.facebook.react.ReactPackage; +import com.facebook.react.bridge.NativeModule; +import com.facebook.react.bridge.ReactApplicationContext; +import com.facebook.react.uimanager.ViewManager; + +import java.util.Collections; +import java.util.List; + +public class RTNCenteredTextPackage implements ReactPackage { + + @Override + public List createViewManagers(ReactApplicationContext reactContext) { + return Collections.emptyList(); + } + + @Override + public List createNativeModules(ReactApplicationContext reactContext) { + return Collections.emptyList(); + } + +} +``` + +The `ReactPackage` interface is used by React Native to understand what native classes the app has to use for the `ViewManager` and `Native Modules` exported by the library. + +## 4. Native Code + +The last step requires you to write some native code to connect the JavaScript side of the Component to what is offered by the platforms. This process requires two main steps: + +1. Run **Codegen** to see what would be generated. +2. Write the native code that will make it work. + +When developing a React Native app that uses a Fabric Component, it is responsibility of the app to actually generate the code using **Codegen**. However, when developing a Fabric Component as a library, it needs to reference the generated code and it is useful to see what the app will generate. + +As first step for both iOS and Android, this guide shows how to execute manually the scripts used by **Codegen** to generate the required code. Further information on **Codegen** can be found [here](./pillars-codegen.md) + +:::caution +The code generated by **Codegen** in this step should not be committed to the versioning system. React Native apps are able to generate the code when the app is built. This allows an app to ensure that all libraries have code generated for the correct version of React Native. +::: + +### iOS + +#### Generate the code - iOS + +To run Codegen for the iOS platform, open a terminal and run the following command: + +```sh +cd MyApp +yarn add ../RTNCenteredText +cd .. +node MyApp/node_modules/react-native/scripts/generate-artifacts.js \ + --path MyApp/ \ + --outputPath RTNCenteredText/generated/ +``` + +This script first adds the `RTNCenteredText` module to the app with `yarn add`. Then, it invokes **Codegen** via the `generate-artifacts.js` script. + +The `--path` option specifies the path to the app, while the `--outputPath` option tells the script where to output the generated code. + +The output of this process is the following folder structure: + +```sh +generated +└── build + └── generated + └── ios + ├── FBReactNativeSpec + │ ├── FBReactNativeSpec-generated.mm + │ └── FBReactNativeSpec.h + ├── RCTThirdPartyFabricComponentsProvider.h + ├── RCTThirdPartyFabricComponentsProvider.mm + └── react + └── renderer + └── components + ├── RTNCenteredTextSpecs + │ ├── ComponentDescriptors.h + │ ├── EventEmitters.cpp + │ ├── EventEmitters.h + │ ├── Props.cpp + │ ├── Props.h + │ ├── RCTComponentViewHelpers.h + │ ├── ShadowNodes.cpp + │ └── ShadowNodes.h + └── rncore + ├── ComponentDescriptors.h + ├── EventEmitters.cpp + ├── EventEmitters.h + ├── Props.cpp + ├── Props.h + ├── RCTComponentViewHelpers.h + ├── ShadowNodes.cpp + └── ShadowNodes.h +``` + +The relevant path for the component is `generated/build/generated/ios/react/renderer/components/RTNCenteredTextSpecs`. +This folder contains all the generated code required by your Component. + +See the [Codegen](./pillars-codegen) section for further details on the generated files. + +:::note +When generating the scaffolding code using **Codegen**, iOS does not clean the `build` folder automatically. If you changed a the Spec name, for example, and then run **Codegen** again, the old files will be retained. +If that happens, remember to remove the `build` folder before running the **Codegen** again. + +``` +cd MyApp/ios +rm -rf build +``` + +::: + +#### Write the Native iOS Code + +Now that the scaffolding code has been generated, it's time to write the Native code for your Fabric Component. +You need to create three files in the `RTNCenteredText/ios` folder: + +1. The `RTNCenteredTextManager.mm`, an Objective-C++ file that declares what the Component exports. +2. The `RTNCenteredText.h`, a header file for the actual view. +3. The `RTNCenteredText.mm`, the implementation of the view. + +##### RTNCenteredTextManager.mm + +```objc title="RTNCenteredTextManager.mm" +#import +#import +#import + +@interface RTNCenteredTextManager : RCTViewManager +@end + +@implementation RTNCenteredTextManager + +RCT_EXPORT_MODULE(RTNCenteredText) + +RCT_EXPORT_VIEW_PROPERTY(text, NSString) + +@end +``` + +This file is the manager for the Fabric Component. The manager objects are used by the React Native runtime to register the modules, the properties and the methods so that they are available to the JavaScript side. + +The most important call is to the `RCT_EXPORT_MODULE` which is required to export the module so that Fabric can retrieve and instantiate it. + +Then, you have to expose the `text` property for the Fabric Component. This is done with the `RCT_EXPORT_VIEW_PROPERTY` macro, specifying a name and a type. + +:::info +There are other macros that can be used to export custom properties, emitters and other constructs. You can view the code that specifies them [here](https://github.com/facebook/react-native/blob/main/React/Views/RCTViewManager.h) +::: + +##### RTNCenteredText.h + +```objc title="RTNCenteredText.h" +#import +#import + +NS_ASSUME_NONNULL_BEGIN + +@interface RTNCenteredText : RCTViewComponentView + +@end + +NS_ASSUME_NONNULL_END +``` + +This file defines the interface for the `RTNCenteredText` view. Here, you can add any native method you may want to invoke on the view. For this guide, you don't need anything, therefore the interface is empty. + +##### RTNCenteredText.mm + +```cpp title="RTNCenteredText.mm" +#import "RTNCenteredText.h" + +#import +#import +#import +#import + +#import "RCTFabricComponentsPlugins.h" + +using namespace facebook::react; + +@interface RTNCenteredText () +@end + +@implementation RTNCenteredText { + UIView *_view; + UILabel *_label; +} + ++ (ComponentDescriptorProvider)componentDescriptorProvider +{ + return concreteComponentDescriptorProvider(); +} + +- (instancetype)initWithFrame:(CGRect)frame +{ + if (self = [super initWithFrame:frame]) { + static const auto defaultProps = std::make_shared(); + _props = defaultProps; + + _view = [[UIView alloc] init]; + _view.backgroundColor = [UIColor redColor]; + + _label = [[UILabel alloc] init]; + _label.text = @"Initial value"; + [_view addSubview:_label]; + + _label.translatesAutoresizingMaskIntoConstraints = false; + [NSLayoutConstraint activateConstraints:@[ + [_label.leadingAnchor constraintEqualToAnchor:_view.leadingAnchor], + [_label.topAnchor constraintEqualToAnchor:_view.topAnchor], + [_label.trailingAnchor constraintEqualToAnchor:_view.trailingAnchor], + [_label.bottomAnchor constraintEqualToAnchor:_view.bottomAnchor], + ]]; + + _label.textAlignment = NSTextAlignmentCenter; + + self.contentView = _view; + } + + return self; +} + +- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps +{ + const auto &oldViewProps = *std::static_pointer_cast(_props); + const auto &newViewProps = *std::static_pointer_cast(props); + + if (oldViewProps.text != newViewProps.text) { + _label.text = [[NSString alloc] initWithCString:newViewProps.text.c_str() encoding:NSASCIIStringEncoding]; + } + + [super updateProps:props oldProps:oldProps]; +} + +@end + +Class RTNCenteredTextCls(void) +{ + return RTNCenteredText.class; +} +``` + +This file contains the actual implementation of the view. + +It starts with some imports which require you to read the files generated by **Codegen**. + +The component has to conform to a specific protocol generated by **Codegen**, in this case `RCTRTNCenteredTextViewProtocol`. + +Then, the file defines a static `(ComponentDescriptorProvider)componentDescriptorProvider` method which is used by Fabric to retrieve the descriptor provider to instantiate the object. + +Then, there is the constructor of the view: the `init` method. In this method, it is important to create a `defaultProps` struct using the `RTNCenteredTextProps` type from **Codegen**. You need to assign it to the private `_props` property to correctly initialize the Fabric Component. The remaining part of the initializer is standard Objective-C code to create views and layout them with AutoLayout. + +The last two pieces are the `updateProps` method and the `RTNCenteredTextCls` method. + +The `updateProps` method is invoked by Fabric every time a prop changes in JavaScript. The props passed as parameters are downcasted to the proper `RTNCenteredTextProps` type and then they are used to update the native code if needed. Notice that the superclass method `[super updateProps]` must be invoked as the last statement of this method, otherwise the `props` and `oldProps` struct will have the same values and you'll not be able to use them to make decisions and to update the component. + +Finally, the `RTNCenteredTextCls` is another static method used to retrieve the correct instance of the class at runtime. + +:::caution +Differently from Native Components, Fabric requires to manually implement the `updateProps` method. It's not enough to export properties with the `RCT_EXPORT_XXX` and `RCT_REMAP_XXX` macros. +::: + +### Android + +Android follows some similar steps to iOS. You have to generate the code, and then you have to write some native code to make it works. + +#### Generate the Code - Android + +To generate the code, you need to manually invoke **Codegen**. This is done similarly to what you need to do for iOS: first, you need to add the package to the app and then you need to invoke a script. + +```sh title="Running Codegen for Android" +cd MyApp +yarn add ../RTNCenteredText +cd android +./gradlew generateCodegenArtifactsFromSchema +``` + +This script first adds the package to the app, in the same way iOS does. Then, after moving to the `android` folder, it invokes a Gradle task to generate the scaffolding code. + +:::note +To run **Codegen**, you need to enable the **New Architecture** in the Android app. This can be done by opening the `gradle.properties` files and by switching the `newArchEnabled` property from `false` to `true`. +::: + +The generated code is stored in the `MyApp/node_modules/rtn-centered-text/android/build/generated/source/codegen` folder and it has this structure: + +```title="Android generated code" +codegen +├── java +│ └── com +│ └── facebook +│ └── react +│ └── viewmanagers +│ ├── RTNCenteredTextManagerDelegate.java +│ └── RTNCenteredTextManagerInterface.java +├── jni +│ ├── Android.mk +│ ├── CMakeLists.txt +│ ├── RTNCenteredText-generated.cpp +│ ├── RTNCenteredText.h +│ └── react +│ └── renderer +│ └── components +│ └── RTNCenteredText +│ ├── ComponentDescriptors.h +│ ├── EventEmitters.cpp +│ ├── EventEmitters.h +│ ├── Props.cpp +│ ├── Props.h +│ ├── ShadowNodes.cpp +│ └── ShadowNodes.h +└── schema.json +``` + +You can see that the content of the `codegen/jni/react/renderer/components/RTNCenteredTextSpecs` looks similar to the files created by the iOS counterpart. The `Android.mk` and `CMakeList.txt` files configure the Fabric Component in the app, while the `RTNCenteredTextManagerDelegate.java` and `RTNCenteredTextManagerInterface.java` files are meant use in your manager. + +See the [Codegen](./pillars-codegen) section for further details on the generated files. + +#### Write the Native Android Code + +The native code for the Android side of a Fabric Components requires three pieces: + +1. A `RTNCenteredText.java` that represents the actual view. +2. A `RTNCenteredTextManager.java` to instantiate the view. +3. Finally, you have to fill the implementation of the `RTNCenteredTextPackage.java` created in the previous step. + +The final structure within the Android library should be like this. + +```title="Android Folder Structure" +android +├── build.gradle +└── src + └── main + ├── AndroidManifest.xml + └── java + └── com + └── rtncenteredtext + ├── RTNCenteredText.java + ├── RTNCenteredTextManager.java + └── RTNCenteredTextPackage.java +``` + +##### RTNCenteredText.java + +```java title="RTNCenteredText" +package com.rtncenteredtext; + +import androidx.annotation.Nullable; +import android.content.Context; +import android.util.AttributeSet; +import android.graphics.Color; + +import android.widget.TextView; +import android.view.Gravity; + +public class RTNCenteredText extends TextView { + + public RTNCenteredText(Context context) { + super(context); + this.configureComponent(); + } + + public RTNCenteredText(Context context, @Nullable AttributeSet attrs) { + super(context, attrs); + this.configureComponent(); + } + + public RTNCenteredText(Context context, @Nullable AttributeSet attrs, int defStyleAttr) { + super(context, attrs, defStyleAttr); + this.configureComponent(); + } + + private void configureComponent() { + this.setBackgroundColor(Color.RED); + this.setGravity(Gravity.CENTER_HORIZONTAL); + } +} +``` + +This class represents the actual view Android is going to represent on screen. It inherit from `TextView` and it configures the basic aspects of itself using a private `configureComponent()` function. + +##### RTNCenteredTextManager.java + +```java title="RTNCenteredTextManager.java" +package com.rtncenteredtext; + +import androidx.annotation.NonNull; +import androidx.annotation.Nullable; + +import com.facebook.react.bridge.ReadableArray; +import com.facebook.react.bridge.ReactApplicationContext; +import com.facebook.react.module.annotations.ReactModule; +import com.facebook.react.uimanager.SimpleViewManager; +import com.facebook.react.uimanager.ThemedReactContext; +import com.facebook.react.uimanager.ViewManagerDelegate; +import com.facebook.react.uimanager.annotations.ReactProp; +import com.facebook.react.viewmanagers.RTNCenteredTextManagerInterface; +import com.facebook.react.viewmanagers.RTNCenteredTextManagerDelegate; + + +@ReactModule(name = RTNCenteredTextManager.NAME) +public class RTNCenteredTextManager extends SimpleViewManager + implements RTNCenteredTextManagerInterface { + + private final ViewManagerDelegate mDelegate; + + static final String NAME = "RTNCenteredText"; + + public RTNCenteredTextManager(ReactApplicationContext context) { + mDelegate = new RTNCenteredTextManagerDelegate<>(this); + } + + @Nullable + @Override + protected ViewManagerDelegate getDelegate() { + return mDelegate; + } + + @NonNull + @Override + public String getName() { + return RTNCenteredTextManager.NAME; + } + + @NonNull + @Override + protected RTNCenteredText createViewInstance(@NonNull ThemedReactContext context) { + return new RTNCenteredText(context); + } + + @Override + @ReactProp(name = "text") + public void setText(RTNCenteredText view, @Nullable String text) { + view.setText(text); + } +} +``` + +The `RTNCenteredTextManager` is a class used by React Native to instantiate the native component. It is the class that implements the interfaces generated by **Codegen** (see the `RTNCenteredTextManagerInterface` interface in the `implements` clause) and it uses the `RTNCenteredTextManagerDelegate` class. + +It is also responsible for exporting all the constructs required by React Native: the class itself is annotated with `@ReactModule` and the `setText` method is annotated with `@ReactProp`. + +##### RTNCenteredTextPackage.java + +Finally, open the `RTNCenteredTextPackage.java` file in the `android/src/main/java/com/rtncenteredtext` folder and update it with the following lines + +```diff title="RTNCenteredTextPackage update" +package com.rtncenteredtext; + +import com.facebook.react.ReactPackage; +import com.facebook.react.bridge.NativeModule; +import com.facebook.react.bridge.ReactApplicationContext; +import com.facebook.react.uimanager.ViewManager; + +import java.util.Collections; +import java.util.List; + +public class RTNCenteredTextPackage implements ReactPackage { + + @Override + public List createViewManagers(ReactApplicationContext reactContext) { ++ return Collections.singletonList(new RTNCenteredTextManager(reactContext));; + } + + @Override + public List createNativeModules(ReactApplicationContext reactContext) { + return Collections.emptyList(); + } + +} +``` + +The added lines instantiate a new `RTNCenteredTextManager` object so that the React Native runtime can use it to render our Fabric Component. + +## 5. Adding the Fabric Component To Your App + +This is the last step to finally see your Fabric Component running on your app. + +### Shared + +First of all, you need to add the NPM package which contains the Component to the app. This can be done with the following command: + +```sh +cd MyApp +yarn add ../RTNCenteredText +``` + +This command adds the `RTNCenteredText` Component to the `node_modules` of your app. + +### iOS + +Then, you need to install the new dependencies in your iOS project. To do so, you need to run these commands: + +```sh +cd ios +RCT_NEW_ARCH_ENABLED=1 bundle exec pod install +``` + +This command installs the iOS dependencies for the project. The `RCT_NEW_ARCH_ENABLED=1` flag instructs **Cocoapods** that it has to execute some additional operations to run **Codegen**. + +:::note +You may have to run `bundle install` once before you can use `RCT_NEW_ARCH_ENABLED=1 bundle exec pod install`. You won't need to run `bundle install` anymore, unless you need to change the ruby dependencies. +::: + +### Android + +Android configuration requires to enable the **New Architecture**. + +1. Open the `android/gradle.properties` file +2. Scroll down to the end of the file and switch the `newArchEnabled` property from `false` to `true`. + +### JavaScript + +Finally, you can read the Component in your JavaScript application. +To do so, you have to: + +1. Import the Component in the js file that uses it. So, if you want to use it in the `App.js`, you need to add this line: + + ```js title="App.js" + import RTNCenteredText from 'rtn-centered-text/js/RTNCenteredTextNativeComponent'; + ``` + +2. Then, you need to use it in another React Native component. The syntax is the same as for any other component: + ```js title="App.js" + // ... other code + const App: () => Node = () => { + // ... other App code ... + return ( + // ...other React Native elements... + + // ...other React Native Elements + ); + }; + ``` + +Now, you can run the React Native app and see your Component on the screen. diff --git a/docs/the-new-architecture/pillars-turbomodule.md b/docs/the-new-architecture/pillars-turbomodule.md new file mode 100644 index 00000000000..9ccd7a9820f --- /dev/null +++ b/docs/the-new-architecture/pillars-turbomodule.md @@ -0,0 +1,713 @@ +--- +id: pillars-turbomodules +title: TurboModules +--- + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; +import NewArchitectureWarning from '../\_markdown-new-architecture-warning.mdx'; + + + +If you've worked with React Native, you may be familiar with the concept of [Native Modules](../native-modules-intro.md), which allow JavaScript and platform-native code to communicate over the React Native "bridge", which handles cross-platform serialization via JSON. + +TurboModules are the next iteration on Native Modules that provide a few extra [benefits](./why): + +- Strongly typed interfaces that are consistent across platforms +- The ability to write your code in C++, either exclusively or integrated with another native platform language, reducing the need to duplicate implementations across platforms +- Lazy loading of modules, allowing for faster app startup +- The use of JSI, a JavaScript interface for native code, which allows for more efficient communication between native and JavaScript code than the bridge + +This guide will show you how to create a basic TurboModule. + +:::caution +TurboModules only work with the **New Architecture** enabled. +To migrate to the **New Architecture**, follow the [Migration guide](../new-architecture-intro) +::: + +## How to Create a TurboModule + +To create a TurboModule, we need to: + +1. Define the JavaScript specification. +2. Configure the module so that Codegen can generate the scaffolding. +3. Write the native code to finish implementing the module. + +## 1. Folder Setup + +In order to keep the module decoupled from the app, it's a good idea to define the module separately from the app, and then add it as a dependency to your app later. This is also what you'll do for writing TurboModules that can be released as open-source libraries later. + +Next to your application, create a folder called `RTNCalculator`. **RTN** stands for "**R**eac**t** **N**ative", and is a recommended prefix for React Native modules. + +Within `RTNCalculator`, create three subfolders: `js`, `ios`, and `android`. + +The final result should look like this: + +```sh +TurboModulesGuide +├── MyApp +└── RTNCalculator + ├── android + ├── ios + └── js +``` + +## 2. JavaScript Specification + +The **New Architecture** requires interfaces specified in a typed dialect of JavaScript (either [Flow](https://flow.org/) or [TypeScript](https://www.typescriptlang.org/)). **Codegen** will use these specifications to generate code in strongly-typed languages, including C++, Objective-C++, and Java. + +There are two requirements the file containing this specification must meet: + +1. The file **must** be named `Native`, with a `.js` or `.jsx` extension when using Flow, or a `.ts`, or `.tsx` extension when using TypeScript. Codegen will only look for files matching this pattern. +2. The file must export a `TurboModuleRegistrySpec` object. + + + + +```typescript title="NativeCalculator.js" +// @flow +import type { TurboModule } from 'react-native/Libraries/TurboModule/RCTExport'; +import { TurboModuleRegistry } from 'react-native'; + +export interface Spec extends TurboModule { + add(a: number, b: number): Promise; +} +export default (TurboModuleRegistry.get( + 'RTNCalculator' +): ?Spec); +``` + + + + +```typescript title="NativeCalculator.ts" +import type { TurboModule } from 'react-native/Libraries/TurboModule/RCTExport'; +import { TurboModuleRegistry } from 'react-native'; + +export interface Spec extends TurboModule { + add(a: number, b: number): Promise; +} + +export default TurboModuleRegistry.get( + 'RTNCalculator' +) as Spec | null; +``` + + + + +At the beginning of the spec files are the imports: + +- The `TurboModule` type, which defines the base interface for all TurboModules +- The `TurboModuleRegistry` JavaScript module, which contains functions for loading TurboModules + +The second section of the file contains the interface specification for the TurboModule. In this case, the interface defines the `add` function which takes two numbers and returns a promise that resolves to a number. This interface type **must** be named `Spec` for a TurboModule. + +Finally, we invoke `TurboModuleRegistry.get`, passing the module's name, which will load the TurboModule if it's available. + +:::caution +We are writing JavaScript files importing types from libraries, without setting up a proper node module and installing its dependencies. Your IDE will not be able to resolve the import statements and you may see errors and warnings. This is expected and will not cause problems when you add the module to your app. +::: + +## 3. Module Configuration + +Next, you need to add some configuration for [**Codegen**](pillars-codegen.md) and auto-linking. + +Some of these configuration files are shared between iOS and Android, while the others are platform-specific. + +### Shared + +The shared configuration is a `package.json` file that will be used by yarn when installing your module. Create the `package.json` file in the root of the `RTNCalculator` directory. + +```json title="package.json" +{ + "name": "rtn-calculator", + "version": "0.0.1", + "description": "Add numbers with TurboModules", + "react-native": "js/index", + "source": "js/index", + "files": [ + "js", + "android", + "ios", + "rtn-calculator.podspec", + "!android/build", + "!ios/build", + "!**/__tests__", + "!**/__fixtures__", + "!**/__mocks__" + ], + "keywords": ["react-native", "ios", "android"], + "repository": "https://github.com//rtn-calculator", + "author": " (https://github.com/)", + "license": "MIT", + "bugs": { + "url": "https://github.com//rtn-calculator/issues" + }, + "homepage": "https://github.com//rtn-calculator#readme", + "devDependencies": {}, + "peerDependencies": { + "react": "*", + "react-native": "*" + }, + "codegenConfig": { + "name": "RTNCalculatorSpec", + "type": "modules", + "jsSrcsDir": "js", + "android": { + "javaPackageName": "com.calculator" + } + } +} +``` + +The upper part of the file contains some descriptive information like the name of the component, its version and its source files. Make sure to update the various placeholders which are wrapped in `<>`: replace all the occurrences of the ``, ``, and `` tokens. + +Then there are the dependencies for this package. For this guide, you need `react` and `react-native`. + +Finally, the **Codegen** configuration is specified by the `codegenConfig` field. It contains an array of libraries, each of which is defined by three other fields: + +- `name`: The name of the library. By convention, you should add the `Spec` suffix. +- `type`: The type of module contained by this package. In this case, it is a TurboModule, thus the value to use is `modules`. +- `jsSrcsDir`: the relative path to access the `js` specification that is parsed by **Codegen**. +- `android.javaPackageName`: the package to use in the Java files generated by **Codegen**. + +### iOS: Create the `podspec` file + +For iOS, you'll need to create a `rtn-calculator.podspec` file which will define the module as a dependency for your app. It will stay in the root of `RTNCalculator`, alongside the `ios` folder. + +The file will look like this: + +```ruby title="rtn-calculator.podspec" +require "json" + +package = JSON.parse(File.read(File.join(__dir__, "package.json"))) + +folly_version = '2021.07.22.00' +folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32' + +Pod::Spec.new do |s| + s.name = "rtn-calculator" + s.version = package["version"] + s.summary = package["description"] + s.description = package["description"] + s.homepage = package["homepage"] + s.license = package["license"] + s.platforms = { :ios => "11.0" } + s.author = package["author"] + s.source = { :git => package["repository"], :tag => "#{s.version}" } + + s.source_files = "ios/**/*.{h,m,mm,swift}" + + s.dependency "React-Core" + + s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1" + s.pod_target_xcconfig = { + "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\"", + "OTHER_CPLUSPLUSFLAGS" => "-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1", + "CLANG_CXX_LANGUAGE_STANDARD" => "c++17" + } + + s.dependency "React-Codegen" + s.dependency "RCT-Folly", folly_version + s.dependency "RCTRequired" + s.dependency "RCTTypeSafety" + s.dependency "ReactCommon/turbomodule/core" +end +``` + +The `.podspec` file has to be a sibling of the `package.json` file and its name is the one we set in the `package.json`'s `name` property: `rtn-calculator`. + +The first part of the file prepares some variables we will use throughout the rest of it. Then, there is a section that contains some information used to configure the pod, like its name, version, and description. Finally, we have a set of dependencies that are required by the New Architecture. + +### Android: `build.gradle`, `AndroidManifest.xml`, a `ReactPackage` class + +To prepare Android to run **Codegen** you have to create three files: + +1. The `build.gradle` with the **Codegen** configuration +1. The `AndroidManifest.xml` file +1. A java class that implements the `ReactPackage` interface. + +At the end of these steps, the `android` folder should look like this: + +```title="Android Folder Structure" +android +├── build.gradle +└── src + └── main + ├── AndroidManifest.xml + └── java + └── com + └── rtncalculator + └── RTNCalculatorPackage.java +``` + +#### The `build.gradle` file + +First, create a `build.gradle` file in the `android` folder, with the following contents: + +```kotlin title="build.gradle" +buildscript { + ext.safeExtGet = {prop, fallback -> + rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback + } + repositories { + google() + gradlePluginPortal() + } + dependencies { + classpath("com.android.tools.build:gradle:7.1.1") + } +} + +apply plugin: 'com.android.library' +apply plugin: 'com.facebook.react' + +android { + compileSdkVersion safeExtGet('compileSdkVersion', 31) +} + +repositories { + maven { + // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm + url "$projectDir/../node_modules/react-native/android" + } + mavenCentral() + google() +} + +dependencies { + implementation 'com.facebook.react:react-native:+' +} +``` + +#### The `AndroidManifest.xml` + +Second, create an `android/src/main` folder. Inside that folder, create a `AndroidManifest.xml` file, with the following code: + +```xml title="AndroidManifest.xml" + + +``` + +This is a small manifest file that defines the package for your module. + +#### The `ReactPackage` class + +Finally, you need a class that extends the `TurboReactPackage` interface. To run the **Codegen** process, you don't have to completely implement the package class: an empty implementation is enough for the app to pick up the module as a proper React Native dependency and to try and generate the scaffolding code. + +Create an `android/src/main/java/com/rtncalculator` folder and, inside that folder, create a `RTNCalculatorPackage.java` file. + +```java title="RTNCalculatorPackage.java" +package com.RTNCalculator; + +import androidx.annotation.Nullable; +import com.facebook.react.bridge.NativeModule; +import com.facebook.react.bridge.ReactApplicationContext; +import com.facebook.react.module.model.ReactModuleInfoProvider; +import com.facebook.react.TurboReactPackage; + +import java.util.Collections; +import java.util.List; + +public class CalculatorPackage extends TurboReactPackage { + + @Nullable + @Override + public NativeModule getModule(String name, ReactApplicationContext reactContext) { + return null; + } + + @Override + public ReactModuleInfoProvider getReactModuleInfoProvider() { + return null; + } +} +``` + +The `ReactPackage` interface is used by React Native to understand what native classes the app has to use for the `ViewManager` and `Native Modules` exported by the library. + +## 4. Native Code + +For the final step in getting your TurboModule ready to go, you'll need to write some native code to connect the JavaScript side to the native platforms. This process requires two main steps: + +- Run **Codegen** to see what it generates. +- Write your native code, implementing the generated interfaces. + +When developing a React Native app that uses a TurboModule, it is responsibility of the app to actually generate the code using **Codegen**. However, when developing a TurboModule as a library, we need to reference the generated code, and it is therefore useful to see what the app will generate. + +As first step for both iOS and Android, this guide shows how to execute manually the scripts used by **Codegen** to generate the required code. Further information on **Codegen** can be found [here](pillars-codegen.md) + +:::caution +The code generated by **Codegen** in this step should not be committed to the versioning system. React Native apps are able to generate the code when the app is built. This allows an app to ensure that all libraries have code generated for the correct version of React Native. +::: + +### iOS + +#### Generate the code - iOS + +To run Codegen for the iOS platform, we need to open a terminal and run the following command: + +```sh title="Running Codegen for iOS" +cd MyApp +yarn add ../RTNCalculator +cd .. +node MyApp/node_modules/react-native/scripts/generate-artifacts.js \ + --path MyApp/ \ + --outputPath RTNCalculator/generated/ +``` + +This script first adds the `RTNCalculator` module to the app with `yarn add`. Then, it invokes Codegen via the `generate-artifacts.js` script. + +The `--path` option specifies the path to the app, while the `--outputPath` option tells Codegen where to output the generated code. + +The output of this process is the following folder structure: + +```sh +generated +└── build + └── generated + └── ios + ├── FBReactNativeSpec + │ ├── FBReactNativeSpec-generated.mm + │ └── FBReactNativeSpec.h + ├── RCTThirdPartyFabricComponentsProvider.h + ├── RCTThirdPartyFabricComponentsProvider.mm + ├── RTNCalculatorSpec + │ ├── RTNCalculatorSpec-generated.mm + │ └── RTNCalculatorSpec.h + └── react + └── renderer + └── components + └── rncore + ├── ComponentDescriptors.h + ├── EventEmitters.cpp + ├── EventEmitters.h + ├── Props.cpp + ├── Props.h + ├── RCTComponentViewHelpers.h + ├── ShadowNodes.cpp + └── ShadowNodes.h +``` + +The relevant path for the TurboModule interface is `generated/build/generated/ios/RTNCalculatorSpec`. + +See the [Codegen](./pillars-codegen) section for further details on the generated files. + +:::note +When generating the scaffolding code using **Codegen**, iOS does not clean the `build` folder automatically. If you changed a the Spec name, for example, and then run **Codegen** again, the old files will be retained. +If that happens, remember to remove the `build` folder before running the **Codegen** again. + +``` +cd MyApp/ios +rm -rf build +``` + +::: + +#### Write the Native iOS Code + +Now add the Native code for your TurboModule. Create two files in the `RTNCalculator/ios` folder: + +1. The `RTNCalculator.h`, a header file for the module. +2. The `RTNCalculator.mm`, the implementation of the module. + +##### RTNCalculator.h + +```objc title="RTNCalculator.h" +#import + +NS_ASSUME_NONNULL_BEGIN + +@interface RTNCalculator : NSObject + +@end + +NS_ASSUME_NONNULL_END +``` + +This file defines the interface for the `RTNCalculator` module. Here, we can add any native method we may want to invoke on the view. For this guide, we don't need anything, therefore the interface is empty. + +##### RTNCalculator.mm + +```objc title="RTNCalculator.mm" +#import "RTNCalculatorSpec.h" +#import "RTNCalculator.h" + +@implementation RTNCalculator + +RCT_EXPORT_MODULE(RTNCalculator) + +RCT_REMAP_METHOD(add, addA:(NSInteger)a + andB:(NSInteger)b + withResolver:(RCTPromiseResolveBlock) resolve + withRejecter:(RCTPromiseRejectBlock) reject) +{ + NSNumber *result = [[NSNumber alloc] initWithInteger:a+b]; + resolve(result); +} + +- (std::shared_ptr)getTurboModule: + (const facebook::react::ObjCTurboModule::InitParams &)params +{ + return std::make_shared(params); +} + +@end +``` + +The most important call is to the `RCT_EXPORT_MODULE`, which is required to export the module so that React Native can load the TurboModule. + +Then the `RCT_REMAP_METHOD` macro is used to expose the `add` method. + +Finally, the `getTurboModule` method gets an instance of the TurboModule so that the JavaScript side can invoke its methods. The function is defined in (and requested by) the `RTNCalculatorSpec.h` file that was generated earlier by Codegen. + +:::info +There are other macros that can be used to export modules and methods. You view the code that specifies them [here](https://github.com/facebook/react-native/blob/main/React/Base/RCTBridgeModule.h). +::: + +### Android + +Android follows similar steps to iOS. We have to generate the code for Android, and then we have to write some native code to make it work. + +#### Generate the Code - Android + +To generate the code for Android, we need to manually invoke Codegen. This is done similarly to what we did for iOS: first, we need to add the package to the app and then we need to invoke a script. + +```sh title="Running Codegen for Android" +cd MyApp +yarn add ../RTNCalculator +cd android +./gradlew generateCodegenArtifactsFromSchema +``` + +This script first adds the package to the app, in the same way iOS does. Then, after moving to the `android` folder, it invokes a Gradle task to create the generated code. + +:::note +To run **Codegen**, you need to enable the **New Architecture** in the Android app. This can be done by opening the `gradle.properties` files and by switching the `newArchEnabled` property from `false` to `true`. +::: + +The generated code is stored in the `MyApp/node_modules/rtn-calculator/android/build/generated/source/codegen` folder and it has this structure: + +```title="Android generated code" +codegen +├── java +│ └── com +│ └── RTNCalculator +│ └── NativeCalculatorSpec.java +├── jni +│ ├── Android.mk +│ ├── RTNCalculator-generated.cpp +│ ├── RTNCalculator.h +│ └── react +│ └── renderer +│ └── components +│ └── RTNCalculator +│ ├── ComponentDescriptors.h +│ ├── EventEmitters.cpp +│ ├── EventEmitters.h +│ ├── Props.cpp +│ ├── Props.h +│ ├── ShadowNodes.cpp +│ └── ShadowNodes.h +└── schema.json +``` + +#### Write the Native Android Code + +The native code for the Android side of a TurboModule requires: + +1. to create a `RTNCalculatorModule.java` that implements the module. +2. to update the `RTNCalculatorPackage.java` created in the previous step. + +The final structure within the Android library should look like this: + +```title="Android Folder Structure" +android +├── build.gradle +└── src + └── main + ├── AndroidManifest.xml + └── java + └── com + └── RTNCalculator + ├── CalculatorModule.java + └── CalculatorPackage.java +``` + +##### Creating the `CalculatorModule.java` + +```java title="CalculatorModule.java" +package com.RTNCalculator; + +import androidx.annotation.NonNull; +import com.facebook.react.bridge.NativeModule; +import com.facebook.react.bridge.Promise; +import com.facebook.react.bridge.ReactApplicationContext; +import com.facebook.react.bridge.ReactContext; +import com.facebook.react.bridge.ReactContextBaseJavaModule; +import com.facebook.react.bridge.ReactMethod; +import java.util.Map; +import java.util.HashMap; + +public class CalculatorModule extends NativeCalculatorSpec { + + public static String NAME = "RTNCalculator"; + + CalculatorModule(ReactApplicationContext context) { + super(context); + } + + @Override + @NonNull + public String getName() { + return NAME; + } + + @Override + public void add(double a, double b, Promise promise) { + promise.resolve(a + b); + } +} +``` + +This class implements the module itself, which extends the `NativeCalculatorSpec` that was generated from the `NativeCalculator` JavaScript specification file. + +##### Updating the `CalculatorPackage.java` + +```diff title="CalculatorPackage.java" +package com.RTNCalculator; + +import androidx.annotation.Nullable; +import com.facebook.react.bridge.NativeModule; +import com.facebook.react.bridge.ReactApplicationContext; ++ import com.facebook.react.module.model.ReactModuleInfo; +import com.facebook.react.module.model.ReactModuleInfoProvider; +import com.facebook.react.TurboReactPackage; + +import java.util.Collections; +import java.util.List; ++ import java.util.HashMap; ++ import java.util.Map; + +public class CalculatorPackage extends TurboReactPackage { + + @Nullable + @Override + public NativeModule getModule(String name, ReactApplicationContext reactContext) { ++ if (name.equals(CalculatorModule.NAME)) { ++ return new CalculatorModule(reactContext); ++ } else { + return null; ++ } + } + + + @Override + public ReactModuleInfoProvider getReactModuleInfoProvider() { +- return null; ++ return () -> { ++ final Map moduleInfos = new HashMap<>(); ++ moduleInfos.put( ++ CalculatorModule.NAME, ++ new ReactModuleInfo( ++ CalculatorModule.NAME, ++ CalculatorModule.NAME, ++ false, // canOverrideExistingModule ++ false, // needsEagerInit ++ true, // hasConstants ++ false, // isCxxModule ++ true // isTurboModule ++ )); ++ return moduleInfos; ++ }; + } +} +``` + +This is the last piece of Native Code for Android. It defines the `TurboReactPackage` object that will be used by the app to load the module. + +## 5. Adding the TurboModule to your App + +Now you can install and use the TurboModule in your app. + +### Shared + +First of all, we need to add the NPM package which contains the Component to the app. This can be done with the following command: + +```sh +cd MyApp +yarn add ../RTNCalculator +``` + +This command will add the `RTNCalculator` module to the `node_modules` of your app. + +### iOS + +Then, you need to install the new dependencies in your iOS project. To do so, run these commands: + +```sh +cd ios +RCT_NEW_ARCH_ENABLED=1 bundle exec pod install +``` + +This command will look for all the dependencies of the project and it will install the iOS ones. The `RCT_NEW_ARCH_ENABLED=1` instruct **Cocoapods** that it has to run some additional operations to run **Codegen**. + +:::note +You may have to run `bundle install` once before you can use `RCT_NEW_ARCH_ENABLED=1 bundle exec pod install`. You won't need to run `bundle install` anymore, unless you need to change the Ruby dependencies. +::: + +### Android + +Android configuration requires to enable the **New Architecture**: + +1. Open the `android/gradle.properties` file +2. Scroll down to the end of the file and switch the `newArchEnabled` property from `false` to `true`. + +### JavaScript + +Now you can use your TurboModule calculator in your app! + +Here's an example App.js file using the `add` method: + +```js title="App.js" +/** + * Sample React Native App + * https://github.com/facebook/react-native + * + * @format + * @flow strict-local + */ +import React from 'react'; +import { useState } from 'react'; +import type { Node } from 'react'; +import { + SafeAreaView, + StatusBar, + Text, + Button +} from 'react-native'; +import RTNCalculator from 'rtn-calculator/js/NativeCalculator.js'; + +const App: () => Node = () => { + const [result, setResult] = useState(null); + return ( + + + + 3+7={result ?? '??'} + +