Skip to content

Commit 8695b78

Browse files
committed
Create Native Platform docs
1 parent 2ef6410 commit 8695b78

27 files changed

+598
-40
lines changed

.spelling

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ initializer
4646
interop
4747
iOS
4848
ItemGroup
49+
JSValue
4950
KeyEvents
5051
lifecycle
5152
macOS
@@ -80,6 +81,7 @@ Quickstart
8081
react-native
8182
react-native-macos
8283
react-native-windows
84+
reactnative.dev
8385
RefreshControl
8486
repo
8587
repos

docs/autolink-windows-cli.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ Here are the options that `react-native autolink-windows` takes:
3131
| `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI |
3232
| `-h`, `--help` | boolean | Display help for command |
3333

34-
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.
34+
## Telemetry Notice
35+
36+
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.
3537

3638
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.
3739

docs/codegen-windows-cli.md

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,51 @@ Here are the options that `react-native codegen-windows` takes:
2727
| `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI |
2828
| `-h`, `--help` | boolean | Display help for command |
2929

30-
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.
30+
## Codegen Config
31+
32+
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:
33+
34+
| Field | Type| Description |
35+
|:------|:---:|:------------|
36+
| `type` | string | `"modules"` for Native Modules, `"components"` for Native Components, or `"all"` for both |
37+
| `jsSrcDir` | string | Path to the TypeScript spec input files |
38+
| `windows` | object | Windows-specific codegen configuration |
39+
40+
The `windows` object is configured as follows:
41+
42+
| Field | Type| Description |
43+
|:------|:---:|:------------|
44+
| `namespace` | string | The C++ namespace to contain the generated code |
45+
| cppStringType` | string | Optional, the string type to use in C++ code, either `"std::string"` or `std::wstring`. Defaults to `"std::string"` |
46+
| `generators` | array | Optional, array of codegen generator strings, accepting `"modulesWindows"` for Native Modules, `"componentsWindows"` for Native Components. Defaults to `[ "modulesWindows" ]` |
47+
| `outputDirectory` | string | Optional, path to place the generated code. Defaults to `./codegen/` of the working directory |
48+
| `separateDataTypes` | boolean | Optional, specify whether to create separate files to define custom data types. Defaults to `false` |
49+
50+
> **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.
51+
52+
### Example Codegen Config
53+
54+
```json
55+
"codegenConfig": {
56+
"name": "NativeModuleSampleSpec",
57+
"type": "all",
58+
"jsSrcsDir": "src",
59+
"includesGeneratedCode": true,
60+
"windows": {
61+
"namespace": "NativeModuleSampleCodegen",
62+
"generators": [
63+
"modulesWindows",
64+
"componentsWindows"
65+
],
66+
"outputDirectory": "windows/NativeModuleSample/codegen",
67+
"separateDataTypes": true
68+
}
69+
},
70+
```
71+
72+
## Telemetry Notice
73+
74+
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.
3175

3276
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.
3377

docs/getting-started.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,12 @@ For information around how to set up React Native, see the [React Native Getting
1515
1616
## Create a new React Native project
1717

18-
Remember to call `@react-native-community/cli init` from the place you want your project directory to live.
18+
Call the following from the place where you want your project directory to live:
1919

2020
<!-- Note, make sure both `@react-native-community/cli@ABC` and `--version "XYZ"` are pointing to the correct NPM tags in the command below. -->
2121

2222
<!-- 1. For the next version (i.e. in docs/getting-started.md) use "next" for the CLI and "nightly" for the RN version -->
23-
<!-- 2. For the latest stable version in versioned_docs use "latest" for both the CLI and RN version -->
24-
<!-- 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" -->
23+
<!-- 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 -->
2524

2625
<!-- See https://www.npmjs.com/package/@react-native-community/cli?activeTab=versions for the CLI version tags. -->
2726
<!-- 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
119118

120119
## Authoring Native Modules
121120

122-
See [Native Modules and React Native Windows](native-modules.md).
121+
See [Native Platform: Overview](native-platform.md).
123122

124123
## Building a standalone React Native Windows App
125124

docs/init-windows-cli.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,20 +30,20 @@ Here are the options that `react-native init-windows` takes:
3030
| `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI |
3131
| `-h`, `--help` | boolean | Display help for command |
3232

33-
### Templates
33+
## Templates
3434

3535
The following templates are available for use with `init-windows` by replacing `--template XYZ`, where `XYZ` can be:
3636

3737
| Template | Name |
3838
|:-:|:--|
39-
| `cpp-app` | React Native Windows Application (New Arch, C++, Win32, Hermes) |
40-
| `cpp-lib` | React Native Windows Turbo Module (New Arch, C++) |
39+
| `cpp-app` | React Native Windows Application (New Arch, WinAppSDK, C++) |
40+
| `cpp-lib` | React Native Windows Library (C++) |
4141
| `old/uwp-cpp-app` | React Native Windows Application (Old Arch, UWP, C++) |
42-
| `old/uwp-cpp-lib` | React Native Windows Library (Old Arch, UWP, C++) |
4342
| `old/uwp-cs-app` | React Native Windows Application (Old Arch, UWP, C#) |
44-
| `old/uwp-cs-lib` | React Native Windows Library (Old Arch, UWP, C#) |
4543

46-
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.
44+
## Telemetry Notice
45+
46+
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.
4747

4848
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.
4949

docs/native-code-language-choice.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Choosing C++ or C# for native code
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
React Native for Windows supports writing native code in both C++ and C#, but there are trade-offs with each language. The choice of language can impact the compatibility, developer experience, and performance of your project. So whether you're building an app or native module, you should choose the native language that best meets your requirements.
1113

1214
> **Note**: In this document, C++ refers specifically to C++/WinRT.

docs/native-code.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Working with native code on Windows
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
## What is a React Native for Windows app?
1113

1214
When you create a React Native for Windows app targeting React Native's old architecture, you will get a [Universal Windows Platform app](https://docs.microsoft.com/windows/uwp/get-started/universal-application-platform-guide) (aka UWP app).

docs/native-modules-advanced.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Native Modules (Advanced)
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
>**This documentation and the underlying platform code is a work in progress.**
1113
>**Examples (C# and C++/WinRT):**
1214
> - [Native Module Sample in `microsoft/react-native-windows-samples`](https://github.com/microsoft/react-native-windows-samples/tree/main/samples-old/NativeModuleSample)

docs/native-modules-async.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Using Asynchronous Windows APIs
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
>**This documentation and the underlying platform code is a work in progress.**
1113
1214
A common scenario for [Native Modules](native-modules.md) is to call one or more native asynchronous methods from a JS asynchronous method. However it may not be immediately obvious how to properly bridge both asynchronous worlds, which can lead to unstable, difficult to debug code.

docs/native-modules-autolinking.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Autolinking Native Modules
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
Autolinking is a mechanism that allows your React Native app project to discover and use native modules and view managers provided by React Native libraries.
1113

1214
This document covers autolinking for the Windows platform. It is an extension to the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md).

docs/native-modules-csharp-codegen.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Compile time code generation for C#
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
>**This documentation and the underlying platform code is a work in progress.**
1113
1214
In previous versions of React Native for Windows, code generation for C# modules was performed using reflection. Since 0.63 we improved this by adding a compile time code generation.

docs/native-modules-jsvalue.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Using JSValue
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
>**This documentation and the underlying platform code is a work in progress.**
1113
1214
`JSValue` is a native, immutable invariant value type, and is meant to hold any of the commonly used JS types: `bool`s, `int`s, `double`s, `string`s, arrays, and objects. It is provided for native developers (writing native modules or view managers) who want an equivalent to the `folly::dynamic` type that is compatible with the WinRT ABI surface provided by `Microsoft.ReactNative`.

docs/native-modules-marshalling-data.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Marshaling Data
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
>**This documentation and the underlying platform code is a work in progress.**
1113
1214
## Overview

docs/native-modules-setup.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Native Module Setup
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
> **This documentation is a work in progress and version-specific. Please check that the version of this document (top of page) matches the version of RN/RNW you're targeting.**
1113
1214
This guide will set you up with our recommendations for authoring a native module for React Native for Windows. After completing this setup, you should be able to answer the question: *Where do I need to implement the native code so it's available at runtime?*

docs/native-modules-troubleshooting.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Troubleshooting Native Modules
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
So you added a new native module or a new method to a module but it isn't working, **now what?!**
1113

1214
## Common Issues

docs/native-modules-using.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Using Community Native Modules
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
Community native modules are usually distributed as npm packages. To understand more about npm packages you may find [this guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) useful.
1113

1214
Consuming native modules requires updating your app's native build files to depend on the module's native build files, called "linking". Many modules support "autolinking", where these updates are done automatically when running the [run-windows command](run-windows-cli.md). Others may require you to link the module manually.

docs/native-modules-vs-turbo-modules.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ title: Native Modules vs Turbo Modules
77

88
> **Architecture Review Needed:** This documentation was written to support development against React Native's "Old" or "Legacy" Architecture. It *may or may not* be directly applicable to New Architecture development and needs to be reviewed and potentially updated. For information on React Native architectures in React Native Windows, see [New vs. Old Architecture](new-architecture.md).
99
10+
> For the latest information on native development on Windows, see [Native Platform: Overview](native-platform.md).
11+
1012
If you've worked with React Native, you may be familiar with the concept of Native Modules, which allow JavaScript and platform-native code to communicate over the React Native "bridge", which handles cross-platform serialization via JSON.
1113

1214
TurboModules are the next iteration of Native Modules that provide a few extra benefits, in particular these modules use JSI, a JavaScript interface for native code, which allows for more efficient communication between native and JavaScript code than the bridge.

0 commit comments

Comments
 (0)