wip: migration guide review

facebook · Jul 6, 2022 · e3408a9 · e3408a9
1 parent f6f3c56
commit e3408a9
Show file tree

Hide file tree

Showing 13 changed files with 183 additions and 198 deletions.
diff --git a/docs/new-architecture-app-intro.md b/docs/new-architecture-app-intro.md
@@ -7,40 +7,25 @@ import NewArchitectureWarning from './\_markdown-new-architecture-warning.mdx';
 
 <NewArchitectureWarning/>
 
-There’s a few prerequisites that should be addressed before the new architecture is enabled in your application.
+There’s a few prerequisites that should be addressed before the New Architecture is enabled in your application.
 
 ## Use a React Native nightly 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.
 
-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 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-20220705-2052-71e89213a`.
 
 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:
+As of this writing, the latest stable release is `0.69.1`. Once you have upgraded your project to this version successfully, you may proceed to targeting the `0.0.0-20220705-2052-71e89213a` nightly release. You may target this nightly release the same way you’d target any other version of React Native:
 
 ```bash
-yarn add react-native@0.0.0-20220201-2008-79975d146
+yarn add react-native@0.0.0-20220705-2052-71e89213a
 ```
 
-## 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`.
-
-```bash
-yarn add react-native-codegen
-```
-
-:::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**
@@ -54,18 +39,6 @@ cd android && ./gradlew wrapper --gradle-version 7.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
-```
-
-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:
 
 ```groovy
@@ -82,7 +55,7 @@ buildscript {
     // ...
     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")
@@ -119,40 +92,18 @@ dependencies {
 
 ## 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.
 
-Please [follow the instructions on the React Native website](hermes) in order to enable Hermes in your application.
+We highly recommend using Hermes in your application. With Hermes enabled, you will be able to use the JavaScript debugger in Flipper to directly debug your JavaScript code.
+
+Please [follow the instructions on the React Native website](hermes) to learn how to enable/disable Hermes.
 
 :::caution
 
 **iOS:** If you opt out of using Hermes, you will need to replace `HermesExecutorFactory` with `JSCExecutorFactory` in any examples used throughout the rest of this guide.
 
 :::
 
-## iOS: Enable C++17 language feature support
-
-Your Xcode project settings need to be updated to support C++17 language features.
-
-**Instructions**
-
-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).
-
-If done correctly, your diff will show the following changes to your project file:
-
-```ruby
-CLANG_CXX_LANGUAGE_STANDARD = "c++17"
-```
-
-:::info
-
-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.
-
-:::
-
 ## iOS: Use Objective-C++ (`.mm` extension)
 
 TurboModules can be written using Objective-C or C++. In order to support both cases, any source files that include C++ code should use the `.mm` file extension. This extension corresponds to Objective-C++, a language variant that allows for the use of a combination of C++ and Objective-C in source files.

diff --git a/docs/new-architecture-app-modules-android.md b/docs/new-architecture-app-modules-android.md
@@ -17,7 +17,7 @@ In this iteration of the guide we’re setting up the project to let you build f
 
 :::
 
-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:
 
@@ -36,10 +36,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"
+                }
             }
         }
     }

diff --git 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
@@ -83,20 +83,6 @@ The way to render your app with Fabric depends on your setup. Here is an example
 #endif
 ```
 
-## 3. Add Babel Plugins
-
-This will trigger the codegen that will run at the metro building time.
-
-```javascript title="babel.config.js"
-module.exports = {
-  presets: ['module:metro-react-native-babel-preset'],
-  plugins: [
-    '@babel/plugin-proposal-class-properties',
-    './node_modules/react-native/packages/babel-plugin-codegen'
-  ]
-};
-```
-
 ## 4. Run pod install
 
 ```bash

diff --git a/docs/new-architecture-appendix.md b/docs/new-architecture-appendix.md
@@ -27,11 +27,31 @@ You may use the following table as a reference for which types are supported and
 
 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`                                       | <code>string &#124; null </code>                         | `String`                             | `NSString`                                                     |                                                                                |
+| `boolean`                                      | <code>boolean &#124; null </code>                        | `Boolean`                            | `NSNumber`                                                     |                                                                                |
+| `Float`, `Double`, or `Int32`                  | No                                                       | `double`                             | `NSNumber`                                                     |                                                                                |
+| <code>{&#124; foo: string, ... &#124;}</code>  | <code>{&#124; foo: string, ...&#124;} &#124; null</code> |                                      |                                                                | Object literal. This is recommended over simply using Object, for type safety. |
+| `Object`                                       | <code>Object &#124; null </code>                         | `ReadableMap`                        | `@{} (untyped dictionary)`                                     | Recommended to use object literal (see above).                                 |
+| `Array<*>`                                     | <code>Array<\*> &#124; null </code>                      | `ReadableArray`                      | `NSArray` (or `RCTConvertVecToArray` when used inside objects) |                                                                                |
+| `Function`                                     | <code>Function &#124; null </code>                       |                                      |                                                                |                                                                                |
+| `Promise<*>`                                   | <code>Promise<\*> &#124; null </code>                    | `com.facebook.react.bridge.Promise`  | `RCTPromiseResolve` and `RCTPromiseRejectBlock`                |                                                                                |
+| Type aliases of the above                      | Yes                                                      |                                      |                                                                |                                                                                |
+| Type Unions <code>'SUCCESS'&#124;'FAIL'</code> | 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:
 
@@ -40,7 +60,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
@@ -82,12 +102,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
@@ -104,7 +124,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
@@ -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';
@@ -28,4 +28,5 @@ The guide is divided into three sections:
   - Enabling the New Renderer (Fabric) in your App
     - [Android](new-architecture-app-renderer-android)
     - [iOS](new-architecture-app-renderer-ios)
+- [**Troubleshooting**](new-architecture-troubleshooting)
 - [**Appendix**](new-architecture-appendix)