-
Notifications
You must be signed in to change notification settings - Fork 4.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Turbo Native Modules - Documentation ported from reactwg #4283
Merged
Merged
Changes from 11 commits
Commits
Show all changes
26 commits
Select commit
Hold shift + click to select a range
7d0be8a
[NA] Turbo Native Modules: add docs
blakef 5444a75
feat: Add New Architecture Appendix
blakef 30d1374
fix: update codegen docs with current CLI
blakef a55c67c
docs: improve turbo native modules file layout
blakef cfc7bd1
docs: Add syntax highlighing comments for diffs
blakef 892edfc
docs: Add Fabric Native Modules placeholders
blakef 883a758
TM: Android: Add video of built app
blakef 9cf22c9
TM: Sidebar simpler labels
blakef 62c925f
TM: Fix internal links
blakef 7af6cd3
TM: fix links + add codegen notes
blakef d7ec9ab
TM: fix language linter issues
blakef 557b8a5
TM: Add iOS documentation
blakef b451ee7
Fix: first round of feedback
blakef dfd38db
fix: lint error
blakef b3ab2a0
TM: Consolidate appendix into a single table
blakef 7971b83
chore: fix links
blakef 33a3e0b
chore: fixup final round of feedback
blakef da4725d
TNM: add code example file paths
blakef 416b9ce
Fix empty spaces
cipolleschi 69bb5dc
import TurboModule as type
cipolleschi c4fc0bf
Fix punctuation
cipolleschi 63ae7c3
Merge branch 'main' into turbo-native-modules-update
cipolleschi 96c749a
Fix linter
cipolleschi 851115a
Fix sidebar and titles
cipolleschi cb0e720
Split pod install from output
cipolleschi 0313c06
put back extract library
cipolleschi File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
import React from "react"; | ||
import IOSContent from "./turbo-native-modules-ios.md"; | ||
import AndroidContent from "./turbo-native-modules-android.md"; | ||
|
||
export function TurboNativeModulesIOS() { | ||
return <IOSContent />; | ||
} | ||
|
||
export function TurboNativeModulesAndroid() { | ||
return <AndroidContent />; | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,210 @@ | ||
# Appendix | ||
|
||
## I. Terminology | ||
|
||
- **Schema** - TypeScript or Flow code that describes the API for a Turbo Native Module or Fabric Native component. Used by **Codegen** to generate boilerplate code. | ||
|
||
* **Turbo Native Modules** - Native libraries that have no “view” for the user. Examples would be persistent storage, notifications, network events. These are accessible to your JavaScript application code as functions and objects. | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* **Fabric Native Component** - Native platform views that are available to your application JavaScript code through React Components. | ||
|
||
- **Legacy Native Components** - Components which are running on the old React Native architecture. | ||
- **Legacy Native Modules** - Modules which are running on the old React Native architecture. | ||
|
||
## II. Codegen Typings | ||
|
||
<!-- These should all be squashed into a single table --> | ||
|
||
### Flow | ||
|
||
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? | <code>?{| foo: string, ...|}</code> | | ||
| Android (Java) | - | | ||
| iOS | - | | ||
cipolleschi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
#### `Object` | ||
|
||
:::info | ||
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` | | ||
|
||
:::info | ||
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. | ||
::: | ||
|
||
### TypeScript | ||
|
||
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? | <code>string | null</code> | | ||
| Android (Java) | `String` | | ||
| iOS | `NSString` | | ||
|
||
#### `boolean` | ||
|
||
| | | | ||
| ----------------- | -------------------------------- | | ||
| Nullable Support? | <code>boolean | null</code> | | ||
| 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? | <code>?{| foo: string, ...|} | null</code> | | ||
| Android (Java) | - | | ||
| iOS | - | | ||
|
||
#### `Object` | ||
|
||
:::info | ||
Recommended to use [Object literal](#object-literal-1) instead. | ||
::: | ||
|
||
| | | | ||
| ----------------- | ------------------------------- | | ||
| Nullable Support? | <code>Object | null</code> | | ||
| 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? | <code>Function | null</code> | | ||
| 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` | | ||
|
||
:::info | ||
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. | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
--- | ||
id: fabric-native-modules-android | ||
title: 'Fabric Native Modules: Android' | ||
--- | ||
|
||
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; | ||
|
||
:::caution | ||
This is work-in-progress... 👷 | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
--- | ||
id: fabric-native-modules-ios | ||
title: 'Fabric Native Modules: iOS' | ||
--- | ||
|
||
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; | ||
|
||
:::caution | ||
This is work-in-progress... 👷 | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
--- | ||
id: fabric-native-modules-introduction | ||
title: 'Fabric Native Modules' | ||
--- | ||
|
||
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; | ||
|
||
:::caution | ||
This is work-in-progress... 👷 | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
--- | ||
id: native-platform | ||
title: Native Platform | ||
--- | ||
|
||
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; | ||
|
||
Your application may need access to platform features that aren’t directly available from react-native or one of the hundreds of [third-party libraries](https://reactnative.directory/) maintained by the community. Maybe you want to reuse some existing Objective-C, Swift, Java, Kotlin or C++ code without having to reproduce it in JavaScript. Whatever your reason, React Native exposes a powerful set of API to connect your native code to your JavaScript application code. | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
This guide introduces: | ||
|
||
- **Turbo Native Modules:** native libraries that have no “view” for the user. Examples would be persistent storage, notifications, network events. These are accessible to your user as JavaScript functions and objects. | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- **Fabric Native Component:** native platform views that are available to your application JavaScript code through React Components. | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
:::note | ||
You might have previously been familiar with: | ||
|
||
- Legacy Native Modules | ||
- Legacy Native Components | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
These are our deprecated native module and component API. You can still use many of these legacy libraries with the New Architecture thanks to our interop layer. You should consider alternative libraries, upgrade to versions that have 1st class support for the New Architecture or port these libraries yourself to Turbo Native Modules or Fabric Native Components. | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
::: | ||
|
||
The recommended order to read these are: | ||
blakef marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
1. Turbo Native Modules | ||
- [Introduction](turbo-native-modules.md) | ||
- [Android](turbo-native-modules-android.md) | ||
- [iOS](turbo-native-modules-ios.md) | ||
2. Fabric Native Components | ||
- [Introduction](fabric-native-modules.md) | ||
- [Android](fabric-native-modules-android.md) | ||
- [iOS](fabric-native-modules-ios.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
😱 We always use
Spec
for this definition, we never used Schema!There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I got mixed up. Just to confirm, the codegen pipeline is:
Spec
→Schema
→ Platform Code (protocols, interfaces, etc...)?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, but the schema in json is an implementation details that the users should never see.