Create Native Platform docs

Author: jonthysell

.spelling

@@ -46,6 +46,7 @@ initializer
 interop
 iOS
 ItemGroup
+JSValue
 KeyEvents
 lifecycle
 macOS
@@ -80,6 +81,7 @@ Quickstart
 react-native
 react-native-macos
 react-native-windows
+reactnative.dev
 RefreshControl
 repo
 repos

docs/autolink-windows-cli.md

@@ -31,7 +31,9 @@ Here are the options that `react-native autolink-windows` takes:
 | `--no-telemetry`      | boolean    | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI |
 | `-h`, `--help`        | boolean    | Display help for command                         |
 
-This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details.
+## Telemetry Notice
+
+This command sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details.
 
 The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
 

docs/codegen-windows-cli.md

@@ -27,7 +27,51 @@ Here are the options that `react-native codegen-windows` takes:
 | `--no-telemetry`      | boolean    | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI |
 | `-h`, `--help`        | boolean    | Display help for command                         |
 
-This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details.
+## Codegen Config
+
+The `react-native codegen-windows` command is configured by the `codegenConfig` object in the project's `package.json` file. This `codegenConfig` object is shared by all platforms, but the relevant parts for React Native for Windows is configured as follows:
+
+| Field | Type| Description |
+|:------|:---:|:------------|
+| `type` | string | `"modules"` for Native Modules, `"components"` for Native Components, or `"all"` for both |
+| `jsSrcDir` | string | Path to the TypeScript spec input files |
+| `windows` | object | Windows-specific codegen configuration |
+
+The `windows` object is configured as follows:
+
+| Field | Type| Description |
+|:------|:---:|:------------|
+| `namespace` | string | The C++ namespace to contain the generated code |
+| cppStringType` | string | Optional, the string type to use in C++ code, either `"std::string"` or `std::wstring`. Defaults to `"std::string"` |
+| `generators` | array | Optional, array of codegen generator strings, accepting `"modulesWindows"` for Native Modules, `"componentsWindows"` for Native Components. Defaults to `[ "modulesWindows" ]` |
+| `outputDirectory` | string | Optional, path to place the generated code. Defaults to `./codegen/` of the working directory |
+| `separateDataTypes` | boolean | Optional, specify whether to create separate files to define custom data types. Defaults to `false` |
+
+> **Note:** For more information on how to configure the `codegenConfig` object for other platforms, see the [reactnative.dev Configuring Codegen](https://reactnative.dev/docs/the-new-architecture/using-codegen#configuring-codegen) page.
+
+### Example Codegen Config
+
+```json
+"codegenConfig": {
+    "name": "NativeModuleSampleSpec",
+    "type": "all",
+    "jsSrcsDir": "src",
+    "includesGeneratedCode": true,
+    "windows": {
+      "namespace": "NativeModuleSampleCodegen",
+      "generators": [
+        "modulesWindows",
+        "componentsWindows"
+      ],
+      "outputDirectory": "windows/NativeModuleSample/codegen",
+      "separateDataTypes": true
+    }
+  },
+```
+
+## Telemetry Notice
+
+This command sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details.
 
 The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
 

docs/getting-started.md

@@ -15,13 +15,12 @@ For information around how to set up React Native, see the [React Native Getting
 
 ## Create a new React Native project
 
-Remember to call `@react-native-community/cli init` from the place you want your project directory to live.
+Call the following from the place where you want your project directory to live:
 
 <!-- Note, make sure both `@react-native-community/cli@ABC` and `--version "XYZ"` are pointing to the correct NPM tags in the command below. -->
 
 <!-- 1. For the next version (i.e. in docs/getting-started.md) use "next" for the CLI and "nightly" for the RN version -->
-<!-- 2. For the latest stable version in versioned_docs use "latest" for both the CLI and RN version -->
-<!-- 3. For older stable versions you'll have to look up the CLI version, but for the RN version use the stable tag name, i.e. "0.73-stable" -->
+<!-- 2. For stable versions in versioned_docs use "latest" for the CLI and the semantic version, i.e. "^0.73.0" for the RN version -->
 
 <!-- See https://www.npmjs.com/package/@react-native-community/cli?activeTab=versions for the CLI version tags. -->
 <!-- See https://www.npmjs.com/package/react-native?activeTab=versions for the RN version tags. -->
@@ -119,7 +118,7 @@ npx react-native init-windows --overwrite
 
 ## Authoring Native Modules
 
-See [Native Modules and React Native Windows](native-modules.md).
+See [Native Platform: Overview](native-platform.md).
 
 ## Building a standalone React Native Windows App
 

docs/init-windows-cli.md

@@ -30,20 +30,20 @@ Here are the options that `react-native init-windows` takes:
 | `--no-telemetry`      | boolean    | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI |
 | `-h`, `--help`        | boolean    | Display help for command                         |
 
-### Templates
+## Templates
 
 The following templates are available for use with `init-windows` by replacing `--template XYZ`, where `XYZ` can be:
 
 | Template | Name |
 |:-:|:--|
-| `cpp-app` | React Native Windows Application (New Arch, C++, Win32, Hermes) |
-| `cpp-lib` | React Native Windows Turbo Module (New Arch, C++) |
+| `cpp-app` | React Native Windows Application (New Arch, WinAppSDK, C++) |
+| `cpp-lib` | React Native Windows Library (C++) |
 | `old/uwp-cpp-app` | React Native Windows Application (Old Arch, UWP, C++) |
-| `old/uwp-cpp-lib` | React Native Windows Library (Old Arch, UWP, C++) |
 | `old/uwp-cs-app` | React Native Windows Application (Old Arch, UWP, C#)  |
-| `old/uwp-cs-lib` | React Native Windows Library (Old Arch, UWP, C#)  |
 
-This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details.
+## Telemetry Notice
+
+This command sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details.
 
 The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
 

docs/native-platform-components-paper.md

@@ -0,0 +1,31 @@
+---
+id: native-platform-components-paper
+title: "Native Platform: Native Components (Paper)"
+sidebar_label: Native Components (Paper)
+---
+
+![Architecture](https://img.shields.io/badge/architecture-old_only-yellow)
+
+This guide covers exposing native UI views from Windows to React Native by implementing a *Native Component* for the Windows platform. For a higher-level overview of native development on Windows, see [Native Platform: Overview](native-platform.md) before reading this guide.
+
+> **Note**: See the [reactnative.dev Native Components guide](https://reactnative.dev/docs/fabric-native-components-introduction) for steps for implementing new Native Components for both the Android and iOS platforms.
+
+> **Architecture Note:** This guide shows how to create a *Paper Native Component* to support React Native's Old Architecture. To support React Native for Windows apps targeting the New Architecture, see [Native Platform: Native Components (Fabric)](native-platform-components.md). For more information on React Native architectures in React Native for Windows, see [New vs. Old Architecture](new-architecture.md).
+
+## High-Level Overview
+
+In order to implement Windows support for a Native Component, you'll need to:
+
+<!-- TODO -->
+
+## Step by Step Guide
+
+### 0. Setup
+
+You'll need a React Native library project initialized with Windows support. The rest of this guide assumes you've followed the [Native Platform: Getting Started](native-platform-getting-started.md) guide to set up a new library.
+
+<!-- TODO -->
+
+## Next Steps
+
+After you've implemented your native library, the final step is consume it in your React Native for Windows app. Continue with [Native Platform: Using Native Libraries](native-platform-using.md).

docs/native-platform-components.md

@@ -0,0 +1,48 @@
+---
+id: native-platform-components
+title: "Native Platform: Native Components (Fabric)"
+sidebar_label: Native Components (Fabric)
+---
+
+![Architecture](https://img.shields.io/badge/architecture-new_only-blue)
+
+This guide covers exposing native UI views from Windows to React Native by implementing a *Native Component* for the Windows platform. For a higher-level overview of native development on Windows, see [Native Platform: Overview](native-platform.md) before reading this guide.
+
+> **Note**: See the [reactnative.dev Native Components guide](https://reactnative.dev/docs/fabric-native-components-introduction) for steps for implementing new Native Components for both the Android and iOS platforms.
+
+> **Architecture Note:** This guide follows the recommendation to create a *Fabric Native Component* to support React Native's New Architecture. To support React Native for Windows apps targeting the Old Architecture, see [Native Platform: Native Components (Paper)](native-platform-components-paper.md). For more information on React Native architectures in React Native for Windows, see [New vs. Old Architecture](new-architecture.md).
+
+## High-Level Overview
+
+In order to implement Windows support for a Native Component, you'll need to:
+
+1. Define the API surface for your Native Component in one or more TypeScript spec files
+2. Use React Native for Windows' Native Module Codegen to take those TypeScript spec files and create the C++ headers for the Windows code
+3. Write the Windows C++ code to implement the *Component View* specified by the generated headers
+4. Use the Native Component in your JavaScript
+
+## Step by Step Guide
+
+### 0. Setup
+
+You'll need a React Native library project initialized with Windows support. The rest of this guide assumes you've followed the [Native Platform: Getting Started](native-platform-getting-started.md) guide to set up a new library.
+
+### 1. Define the API surface in TypeScript
+
+<!-- TODO -->
+
+### 2. Use React Native for Windows' Native Module Codegen
+
+<!-- TODO -->
+
+### 3. Implement the Windows C++ code
+
+<!-- TODO -->
+
+### 4. Use the Native Component in your JavaScript
+
+<!-- TODO -->
+
+## Next Steps
+
+After you've implemented your native library, the final step is consume it in your React Native for Windows app. Continue with [Native Platform: Using Native Libraries](native-platform-using.md).

docs/native-platform-getting-started.md

@@ -0,0 +1,77 @@
+---
+id: native-platform-getting-started
+title: "Native Platform: Getting Started"
+sidebar_label: Getting Started
+---
+
+![Architecture](https://img.shields.io/badge/architecture-new_&_old-green)
+
+Similar to how the [Getting Started for Windows](getting-started.md) guide takes you through the process of creating a base React Native app (which supports iOS and Android), and then *adding* Windows support, this guide will take you through the steps of creating a base React Native library and then *adding* Windows support.
+
+Before you get started, make sure you have installed all of the [development dependencies](rnw-dependencies.md).
+
+> **Note:** There have always been multiple ways to create base React Native libraries, each creating a slightly different setup. This guide uses the `create-react-native-library` tool (with specific options) to start a brand new library, because that is the specific setup tested by the React Native for Windows team. Your experience may differ when attempting to add Windows support to (existing) libraries created by other tools.
+
+## Create a new React Native library project
+
+Call the following from the place where you want your project directory to live:
+
+<!-- Note, make sure `--react-native-version "XYZ"` are pointing to the correct NPM tags in the command below. -->
+
+<!-- 1. For the next version (i.e. in docs/getting-started.md) use "nightly" for the RN version -->
+<!-- 2. For stable versions in versioned_docs use the semantic version, i.e. "^0.73.0" for the RN version -->
+
+<!-- See https://www.npmjs.com/package/react-native?activeTab=versions for the RN version tags. -->
+
+```bat
+npx --yes [email protected] --local false --type turbo-module --react-native-version "nightly" --example vanilla <projectName>
+```
+
+> **Note**: Replace `<projectName>` with the name of your library. The rest of this guide will assume you named your project `testlib`. You will also be prompted to supply several other options (slug, description, etc.) when creating your project. For more information on what these options mean, see [create-react-native-library's documentation](https://callstack.github.io/react-native-builder-bob).
+
+### Navigate into this newly created directory
+
+React Native will have created your project in a new sub-directory, which you must enter before continuing.
+
+```bat
+cd testlib
+```
+
+### Add React Native Windows to your project's dependencies
+
+<!-- Note, make sure "version" is pointing to the correct react-native-windows NPM tag in the command below. -->
+
+<!-- 1. For the next version (i.e. in docs/getting-started.md) use "canary" -->
+<!-- 2. For other versions in versioned_docs use the version in the format "^0.XY.0" -->
+
+```bat
+yarn add react-native-windows@canary --dev
+yarn add react-native-windows@* --peer
+yarn install
+```
+
+### Initialize the React Native Windows native code and projects
+
+Lastly, initialize the React Native for Windows library with the [init-windows command](init-windows-cli.md) and the `cpp-lib` template:
+
+```bat
+npx react-native init-windows --template cpp-lib --overwrite
+```
+
+> **Note:** The command will not only initialize the Windows code for the library project itself, but it will also add and initialize React Native for Windows for the example app created by `create-react-native-library` in the `example` folder.
+
+## Running the React Native Windows example app
+
+If you followed this guide and added Windows support to the base project created by `create-react-native-library`, you should be able to launch the provided `example` app with the [run-windows command](run-windows-cli.md):
+
+```bat
+yarn example react-native run-windows
+```
+
+## Next Steps
+
+After you've initialized a new project with Windows support, your next step is to implement the Windows support in native code.
+
+If you're implementing a Native Module (i.e. exposing non-UI native code), continue with [Native Platform: Native Modules](native-platform-modules.md).
+
+If you're implementing a Native Component (i.e. native Windows views), continue with [Native Platform: Native Components](native-platform-components.md).