Update Codegen Docs (#3974)

* Add codegen CLI and Running codegen in libraries sections * Fix typos * Fixed broken links * Improved wording and formatting * Updated the Invoking the code-gen during development paragraph of the New Architecture Appendix * Added the Naming Conventions section to the New Architecture Appendix * Update docs/new-architecture-appendix.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-appendix.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-appendix.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-appendix.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-appendix.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-appendix.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-library-intro.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/new-architecture-library-intro.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Fixed tabs in Appendix * Swapped Modules and Components section in Appendix * Moved the Benefits paragraph to the top of the section * Made the --outputPath description more accurate * Added suggestin to gitignore the generated code * Deleted the Naming Convention s section from the Appendix as duplicated information * Update docs/the-new-architecture/pillars-codegen.md Co-authored-by: Riccardo Cipolleschi <[email protected]> * Deleted unused imports from the Appendix --------- Co-authored-by: Riccardo Cipolleschi <[email protected]> Co-authored-by: Nick Gerleman <[email protected]>
facebook · Jan 10, 2024 · dc5e212 · dc5e212
1 parent f9115d9
commit dc5e212
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 1 deletion.
diff --git a/docs/new-architecture-appendix.md b/docs/new-architecture-appendix.md
@@ -221,10 +221,23 @@ You may also find it useful to refer to the JavaScript specifications for the co
 
 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:
+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 discription in [The Codegen CLI](the-new-architecture/pillars-codegen#the-codegen-cli) section.
 
 ### Android - Invoking a Gradle task directly
 

diff --git a/docs/new-architecture-library-intro.md b/docs/new-architecture-library-intro.md
@@ -162,6 +162,11 @@ Codegen can be configured in the `package.json` file of your Library. Add the fo
 +    "name": "<library name>",
 +    "type": "all",
 +    "jsSrcsDir": ".",
++    "outputDir": {
++      "ios": "ios/generated",
++      "android": "android/generated"
++    },
++    "includesGeneratedCode": true,
 +    "android": {
 +      "javaPackageName": "com.facebook.fbreact.specs"
 +    }
@@ -173,6 +178,8 @@ Codegen can be configured in the `package.json` file of your Library. Add the fo
 - The `name` field is the name of the library.
 - The `type` field is used to identify the type of module we want to create. We suggest keeping `all` to support libraries that contain both Turbo Native Module and Fabric Native Components.
 - The `jsSrcsDir` is the directory where the codegen will start looking for JavaScript specs.
+- The `outputDir` field is the output directory for the generated code. It can be defined in a platform-independent way, like `"outputDir": "universal/generated"`, or per-platform as in the example above.
+- The `includesGeneratedCode` field tells the Codegen whether this library include generated files. If `true`, the Codegen will not run for this library during the app build.
 - The `android.javaPackageName` is the name of the package where the generated code ends up.
 
 Android also requires to have the [React Gradle Plugin properly configured](new-architecture-app-intro#android-specifics) in your app.

diff --git a/docs/the-new-architecture/pillars-codegen.md b/docs/the-new-architecture/pillars-codegen.md
@@ -230,3 +230,60 @@ The **Codegen** for a Fabric Native Component contains a `MyFabricComponentManag
 Then, there is a layer of JNI C++ files that are used by Fabric to render the components. The basic element for a Fabric Component is the `ShadowNode`: it represents a node in the React abstract 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 on the Fabric Native Component.
+
+## The Codegen CLI
+
+**npx react-native codegen** [**--path** *path*] [**--platform** *string*] [**--outputPath** *path*]
+
+#### DESCRIPTION
+
+This command runs `react-native-codegen` for your project.
+The Codegen must be configured as described in [Configure Codegen](../new-architecture-library-intro#configure-codegen).
+
+The following options are available:
+
+- `--path` - Path to `package.json`. The default path is the current working directory.
+- `--platform` - Target platform. Supported values: `android`, `ios`, `all`. The default value is `all`.
+- `--outputPath` - Output path. The default value is the value defined in `codegenCofig.outputDir`.
+
+#### EXAMPLES
+
+- Read `package.json` from the current working directory, generate code based on its `codegenConfig`.
+
+```sh
+npx react-native codegen
+```
+
+- Read `package.json` from the current working directory, generate iOS code in the location defined in the `codegenConfig`.
+
+```sh
+npx react-native codegen --platform ios
+```
+
+- Read `package.json` from `third-party/some-library`, generate Android code in `third-party/some-library/android/generated`.
+
+```sh
+npx react-native codegen \
+    --path third-party/some-library \
+    --platform android \
+    --outputPath third-party/some-library/android/generated
+```
+
+## Including Generated Code into Libraries
+
+If you are working on a library, you can include Codegen artefacts in it. This setup has a number of benefits:
+
+- No need to rely on the app to run Codegen for you, the generated code is always there.
+- The implementation files are always consistent with the generated interfaces.
+- No need to [include two sets of files](backward-compatibility-turbomodules#android-1) to support the Old and the New Architecture on Android. You can only keep the New Architecture one, and it is guaranteed to be backwards compatible.
+- No need to worry about Codegen version mismatch between what is used by the app, and what was used during library development.
+- Since all native code is there, it is possible to ship the native part of the library as a prebuild.
+
+Here is how you can enable this setup:
+
+- Define `includesGeneratedCode: true` and `outputDir` in the `codegenConfig`, as described in [Configure Codegen](../new-architecture-library-intro#configure-codegen).
+- Run Codegen locally with [the codegen CLI](pillars-codegen#the-codegen-cli).
+- Update your `package.json` to include the generated code.
+- Update your [podspec](pillars-turbomodules#ios-create-the-podspec-file) to include the generated code.
+- Update your [build.gradle file](../the-new-architecture/pillars-turbomodules#the-buildgradle-file) to include the generated code.
+- You may also want to add the generated code to `.gitignore`.