Move New Architecture docs from reactnative.dev

README.md

@@ -1,27 +1,57 @@
 # React Native New Architecture Working Group
 
-This is a discussion-only repository to coordinate and support the rollout of the **React Native New Architecture**. 
-You can access to the working group via the [Discussions Tab on Github](https://github.com/reactwg/react-native-new-architecture/discussions).
+The intention of this repository is to coordinate and support the rollout of the **[React Native New Architecture](https://reactnative.dev/docs/the-new-architecture/landing-page)**. We have provided [guides](#guides) and a [discussion](#discussion) space for this purpose.
 
-The intention of this group is to offer a space where the community can meet and discuss about the New Architecture of React Native (being the Fabric Rendered and the TurboModule system). Moreover, we're going to use this working group to share information and updates with the wider community for the sake of transparency.
+You can find New Architecture updates [here](https://github.com/reactwg/react-native-new-architecture/discussions/categories/releases).
 
-## Sections
+## Guides
+
+- How to enable the New Architecture
+  - [For Apps](./docs/enable-apps.md)
+  - For Libraries
+    - [Prerequisites](./docs/enable-libraries-prerequisites.md)
+    - [For Android](./docs/enable-libraries-android.md)
+    - [For iOS](./docs/enable-libraries-ios.md)
+- New Architecture Workflows
+  - [Create a Fabric Native Component](./docs/fabric-native-components.md)
+  - [Create a Turbo Native Module](./docs/turbo-modules.md)
+  - [Using Codegen](./docs/codegen) to write type-safe Fabric Components and Turbo Modules
+  - Writing [cross-platform TurboModules](./docs/turbo-modules-xplat.md) with C++
+    - Supporting [custom C++ types](./docs/cxx-custom-types.md)
+  - [Using React 18](./docs/react-18.md) features
+  - [Backwards compatibility](./docs/backwards-compat.md)
+    - For [Legacy Native Modules](./docs/backwards-compat-turbo-modules.md)
+    - For [Legacy Native Components](./docs/backwards-compat-fabric-component.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Appendix](./docs/appendix.md)
+
+## Discussion
+
+This repository is also a place for discussion and feedback on the New Architecture. You can access it by heading over to the [Discussions Tab on Github](https://github.com/reactwg/react-native-new-architecture/discussions).
+
+Note: The discussion is **closed by default** and only members of the working group can post.
+
+Everyone is welcome to join the working group.
+If you wish to join the conversation, [please fill in the following form](https://forms.gle/8emgdwFZXuzEpyyn9).
+We will review your application and will give you access soon after.
+
+### Sections
 
 We've created some sections to keep the discussion focused.
 
-| Title | Topic |
-| --- | --- |
-| [Announcements 📣](https://github.com/reactwg/react-native-new-architecture/discussions/categories/announcements) | A place to share milestones and significant updates on the RN New Architecture Rollout |
-| [Deep Dive 🐳](https://github.com/reactwg/react-native-new-architecture/discussions/categories/deep-dive) | A place to chat about deep dives and technical-specific topics |
-| [Documentation 📚](https://github.com/reactwg/react-native-new-architecture/discussions/categories/documentation) | A place to chat about the New Architecture documentation and migration material |
-| [Libraries 🛠](https://github.com/reactwg/react-native-new-architecture/discussions/categories/libraries) | A place to chat about 3rd party libraries and their migration story to the New Architecture |
-| [Q&A 🤝](https://github.com/reactwg/react-native-new-architecture/discussions/categories/q-a) | A place to ask the community for help on the New Architecture topics |
-| [Releases 🏁](https://github.com/reactwg/react-native-new-architecture/discussions/categories/releases) | A place to chat about release specific bugs & build problems |
+| Title                                                                                                             | Topic                                                                                       |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [Announcements 📣](https://github.com/reactwg/react-native-new-architecture/discussions/categories/announcements) | General announcements about this working group.                                             |
+| [Deep Dive 🐳](https://github.com/reactwg/react-native-new-architecture/discussions/categories/deep-dive)         | Sharing deep dives and technical-specific topics                                            |
+| [Documentation 📚](https://github.com/reactwg/react-native-new-architecture/discussions/categories/documentation) | A place to chat about the New Architecture documentation and migration material             |
+| [Libraries 🛠](https://github.com/reactwg/react-native-new-architecture/discussions/categories/libraries)          | A place to chat about 3rd party libraries and their migration story to the New Architecture |
+| [Q&A 🤝](https://github.com/reactwg/react-native-new-architecture/discussions/categories/q-a)                     | A place to ask the community for help on the New Architecture topics                        |
+| [Releases 🏁](https://github.com/reactwg/react-native-new-architecture/discussions/categories/releases)           | Updates on New Architecture in each release                                                 |
 
 ## How to join the working group
 
 This working group is **closed by default**.
 
-Everyone is welcome to join the conversation though. 
+Everyone is welcome to join the conversation though.
 [If you wish to join the conversation, please fill in the following form.](https://forms.gle/8emgdwFZXuzEpyyn9)
 We will review your application and will give you access just after.

docs/appendix.md

@@ -0,0 +1,275 @@
+# Appendix
+
+## I. Terminology
+
+The whole New Architecture related guides will stick to the following **terminology**:
+
+- **Legacy Native Components** - To refer to Components which are running on the old React Native architecture.
+- **Legacy Native Modules** - To refer to Modules which are running on the old React Native architecture.
+- **Fabric Native Components** - To refer to Components which have been adapted to work well with the New Architecture, namely the new renderer. For brevity you might find them referred as **Fabric Components**.
+- **Turbo Native Modules** - To refer to Modules which have been adapted to work well with the New Architecture, namely the new Native Module System. For brevity you might find them referred as **Turbo Modules**
+
+## II. Flow Type 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:
+
+### `string`
+
+| Nullable Support? | `?string` |
+| Android (Java) | `string` |
+| iOS | `NSString` |
+
+### `boolean`
+
+| Nullable Support? | `?boolean` |
+| Android (Java) | `Boolean` |
+| iOS | `NSNumber` |
+
+### Object literal
+
+This is recommended over using plain `Object`, for type safety.
+
+**Example:** `{| foo: string, ... |}`
+
+| Nullable Support? | `?{| foo: string, ...|}` |
+| Android (Java) | - |
+| iOS | - |
+
+### `Object`
+
+> [!NOTE]
+> Recommended to use [Object literal](#object-literal) instead.
+
+| Nullable Support? | `?Object` |
+| Android (Java) | `ReadableMap` |
+| iOS | `@` (untyped dictionary) |
+
+### `Array<*>`
+
+| Nullable Support? | `?Array<*>` |
+| Android (Java) | `ReadableArray` |
+| iOS | `NSArray` (or `RCTConvertVecToArray` when used inside objects) |
+
+### `Function`
+
+| Nullable Support? | `?Function` |
+| Android (Java) | '-' |
+| iOS | '-' |
+
+### `Promise<*>`
+
+| Nullable Support? | `?Promise<*>` |
+| Android (Java) | `com.facebook.react.bridge.Promise` |
+| iOS | `RCTPromiseResolve` and `RCTPromiseRejectBlock` |
+
+### Type Unions
+
+Type unions are only supported as callbacks.
+
+**Example:** `'SUCCESS' | 'FAIL'`
+
+| Nullable Support? | 'Only as callbacks' |
+| Android (Java) | '-' |
+| iOS | '-' |
+
+### Callbacks
+
+Callback functions are not type checked, and are generalized as `Object`s.
+
+**Example:** `() =>`
+
+| Nullable Support? | 'Yes' |
+| Android (Java) | `com.facebook.react.bridge.Callback` |
+| iOS | `RCTResponseSenderBlock` |
+
+> [!Tip]
+> 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. 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:
+
+### `string`
+
+| Nullable Support? | `string | null` |
+| Android (Java) | `String` |
+| iOS | `NSString` |
+
+### `boolean`
+
+| Nullable Support? | `boolean | null` |
+| Android (Java) | `Boolean` |
+| iOS | `NSNumber` |
+
+### `number`
+
+| Nullable Support? | 'No' |
+| Android (Java) | `double` |
+| iOS | `NSNumber` |
+
+### Object literal
+
+This is recommended over using plain `Object`, for type safety.
+
+**Example:** `{| foo: string, ... |}`
+
+| Nullable Support? | `{| foo: string, ...|} | null` |
+| Android (Java) | - |
+| iOS | - |
+
+### `Object`
+
+> [!NOTE]
+> Recommended to use [Object literal](#object-literal-1) instead.
+
+| Nullable Support? | `Object | null` |
+| Android (Java) | `ReadableMap` |
+| iOS | `@` (untyped dictionary) |
+
+### `Array<*>`
+
+| Nullable Support? | `Array<*> | null` |
+| Android (Java) | `ReadableArray` |
+| iOS | `NSArray` (or `RCTConvertVecToArray` when used inside objects) |
+
+### `Function`
+
+| Nullable Support? | `Function | null` |
+| Android (Java) | '-' |
+| iOS | '-' |
+
+### `Promise<*>`
+
+| Nullable Support? | `Promise<*> | null` |
+| Android (Java) | `com.facebook.react.bridge.Promise` |
+| iOS | `RCTPromiseResolve` and `RCTPromiseRejectBlock` |
+
+### Type Unions
+
+Type unions are only supported as callbacks.
+
+**Example:** `'SUCCESS' | 'FAIL'`
+
+| Nullable Support? | 'Only as callbacks' |
+| Android (Java) | '-' |
+| iOS | '-' |
+
+### Callbacks
+
+Callback functions are not type checked, and are generalized as `Object`s.
+
+**Example:** `() =>`
+
+| Nullable Support? | 'Yes' |
+| Android (Java) | `com.facebook.react.bridge.Callback` |
+| iOS | `RCTResponseSenderBlock` |
+
+> [!Tip]
+> 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.
+
+## IV. Invoking the code-gen during development
+
+> This section contains information specific to v0.66 of React Native.
+
+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 three options:
+
+1. Invoking a Gradle task directly (Android).
+2. Invoking a script manually.
+3. Use the Codegen CLI.
+
+### Using the CLI
+
+For the simplest and most common use cases you can use the Codegen CLI. Call the following command in your project directory:
+
+```sh
+npx react-native codegen
+```
+
+This will produce Codegen artefacts in their default locations. You can provide additional options to customize input and output paths, as well as the target platform.
+
+See full description in [The Codegen CLI](./codegen.md#the-codegen-cli) section.
+
+### Android - Invoking a Gradle task directly
+
+You can trigger the Codegen by invoking the following task:
+
+```bash
+./gradlew generateCodegenArtifactsFromSchema --rerun-tasks
+```
+
+The extra `--rerun-tasks` flag is added to make sure Gradle is ignoring the `UP-TO-DATE` checks for this task. You should not need it during normal development.
+
+The `generateCodegenArtifactsFromSchema` task normally runs before the `preBuild` task, so you should not need to invoke it manually, but it will be triggered before your builds.
+
+### Invoking the script manually
+
+Alternatively, you can invoke the Codegen directly, bypassing the Gradle Plugin or CocoaPods infrastructure.
+This can be done with the following commands.
+
+The parameters to provide will look quite familiar to you now that you have already configured the Gradle plugin or CocoaPods library.
+
+#### Generating the schema file
+
+First, you’ll need to generate a schema file from your JavaScript sources. You only need to do this whenever your JavaScript specs change. The script to generate this schema is provided as part of the `react-native-codegen` package. If running this from within your React Native application, you can use the package from `node_modules` directly:
+
+```bash
+node node_modules/react-native-codegen/lib/cli/combine/combine-js-to-schema-cli.js \
+  <output_file_schema_json> <javascript_sources_dir>
+```
+
+> The source for the `react-native-codegen` is available in the React Native repository, under `packages/react-native-codegen`. Run `yarn install` and `yarn build` in that directory to build your own `react-native-codegen` package from source. In most cases, you will not want to do this as the guide assumes the use of the `react-native-codegen` package version that is associated with the relevant React Native nightly release.
+
+#### Generating the native code artifacts
+
+Once you have a schema file for your native modules or components, you can use a second script to generate the actual native code artifacts for your library. You can use the same schema file generated by the previous script.
+
+```bash
+node node_modules/react-native/scripts/generate-specs-cli.js \
+  --platform <ios|android> \
+  --schemaPath <generated_schema_json_file> \
+  --outputDir <output_dir> \
+  [--libraryName library_name] \
+  [--javaPackageName java_package_name] \
+  [--libraryType all(default)|modules|components]
+```
+
+> [!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 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
+node node_modules/react-native-codegen/lib/cli/combine/combine-js-to-schema-cli.js /tmp/schema.json ./js
+
+# Generate native code artifacts
+node node_modules/react-native/scripts/generate-specs-cli.js \
+  --platform ios \
+  --schemaPath /tmp/schema.json \
+  --outputDir ./ios \
+  --libraryName MyLibSpecs \
+  --libraryType modules
+```
+
+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.
+
+## V. 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.
+
+### Finding your bridge delegate
+
+This guide assumes that the `AppDelegate` is configured as the bridge delegate. If you are not sure which is your bridge delegate, then place a breakpoint in `RCTBridge` and `RCTCxxBridge`, run your app, and inspect `self.delegate`.
+
+---
+
+> [!IMPORTANT]
+> This documentation is still experimental and details are subject to changes as we iterate.
+> Feel free to share your feedback on this [discussion](https://github.com/reactwg/react-native-new-architecture/discussions/8).
+>
+> Moreover, it contains **several manual steps**. Please note that this won't be representative of the final developer experience once the New Architecture is stable. We're working on tools, templates and libraries to help you get started fast on the New Architecture, without having to go through the whole setup.