From e167b2654312ab2211749b58fcf1ae8abaa38043 Mon Sep 17 00:00:00 2001 From: Simek Date: Tue, 9 Sep 2025 17:17:19 +0200 Subject: [PATCH] convert all blockquotes to admonitions in unversioned docs --- docs/_getting-started-linux-android.md | 24 ++++-- docs/_getting-started-macos-android.md | 12 ++- docs/_getting-started-windows-android.md | 20 +++-- docs/_remove-global-cli.md | 13 ++-- docs/flatlist.md | 12 ++- docs/legacy/native-modules-android.md | 36 ++++++--- docs/legacy/native-modules-ios.md | 46 +++++++---- docs/linking.md | 77 +++++++++++-------- docs/safeareaview.md | 4 +- docs/sectionlist.md | 6 +- docs/set-up-your-environment.md | 2 +- docs/textinput.md | 14 ++-- docs/the-new-architecture/custom-cxx-types.md | 4 +- docs/view.md | 20 +++-- website/blog/2020-07-06-version-0.63.md | 4 +- ...-update-on-the-new-architecture-rollout.md | 4 +- .../2023-06-21-package-exports-support.md | 22 +++--- 17 files changed, 212 insertions(+), 108 deletions(-) diff --git a/docs/_getting-started-linux-android.md b/docs/_getting-started-linux-android.md index 165dff02d04..9e8473b374b 100644 --- a/docs/_getting-started-linux-android.md +++ b/docs/_getting-started-linux-android.md @@ -26,7 +26,9 @@ Setting up your development environment can be somewhat tedious if you're new to Then, click "Next" to install all of these components. -> If the checkboxes are grayed out, you will have a chance to install these components later on. +:::note +If the checkboxes are grayed out, you will have a chance to install these components later on. +::: Once setup has finalized and you're presented with the Welcome screen, proceed to the next step. @@ -36,7 +38,9 @@ Android Studio installs the latest Android SDK by default. Building a React Nati To do that, open Android Studio, click on "Configure" button and select "SDK Manager". -> The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::tip +The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +::: Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the `Android 15 (VanillaIceCream)` entry, then make sure the following items are checked: @@ -59,17 +63,23 @@ export PATH=$PATH:$ANDROID_HOME/emulator export PATH=$PATH:$ANDROID_HOME/platform-tools ``` -> `.bash_profile` is specific to `bash`. If you're using another shell, you will need to edit the appropriate shell-specific config file. +:::note +`.bash_profile` is specific to `bash`. If you're using another shell, you will need to edit the appropriate shell-specific config file. +::: Type `source $HOME/.bash_profile` for `bash` or `source $HOME/.zprofile` to load the config into your current shell. Verify that ANDROID_HOME has been set by running `echo $ANDROID_HOME` and the appropriate directories have been added to your path by running `echo $PATH`. -> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::note +Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::

Watchman

Follow the [Watchman installation guide](https://facebook.github.io/watchman/docs/install#buildinstall) to compile and install Watchman from source. -> [Watchman](https://facebook.github.io/watchman/docs/install) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later). +:::info +[Watchman](https://facebook.github.io/watchman/docs/install) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later). +:::

Preparing the Android device

@@ -89,7 +99,9 @@ If you use Android Studio to open `./AwesomeProject/android`, you can see the li If you have recently installed Android Studio, you will likely need to [create a new AVD](https://developer.android.com/studio/run/managing-avds.html). Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the **VanillaIceCream** API Level 35 image. -> We recommend configuring [VM acceleration](https://developer.android.com/studio/run/emulator-acceleration.html#vm-linux) on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager. +:::tip +We recommend configuring [VM acceleration](https://developer.android.com/studio/run/emulator-acceleration.html#vm-linux) on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager. +::: Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it. diff --git a/docs/_getting-started-macos-android.md b/docs/_getting-started-macos-android.md index ecf3e1c18ac..6cf6aaa99e2 100644 --- a/docs/_getting-started-macos-android.md +++ b/docs/_getting-started-macos-android.md @@ -65,7 +65,9 @@ Setting up your development environment can be somewhat tedious if you're new to Then, click "Next" to install all of these components. -> If the checkboxes are grayed out, you will have a chance to install these components later on. +::note +If the checkboxes are grayed out, you will have a chance to install these components later on. +::: Once setup has finalized and you're presented with the Welcome screen, proceed to the next step. @@ -77,7 +79,9 @@ To do that, open Android Studio, click on "More Actions" button and select "SDK ![Android Studio Welcome](/docs/assets/GettingStartedAndroidStudioWelcomeMacOS.png) -> The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::tip +The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +::: Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the `Android 15 (VanillaIceCream)` entry, then make sure the following items are checked: @@ -102,7 +106,9 @@ export PATH=$PATH:$ANDROID_HOME/platform-tools Run `source ~/.zprofile` (or `source ~/.bash_profile` for `bash`) to load the config into your current shell. Verify that ANDROID_HOME has been set by running `echo $ANDROID_HOME` and the appropriate directories have been added to your path by running `echo $PATH`. -> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::note +Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::

Preparing the Android device

diff --git a/docs/_getting-started-windows-android.md b/docs/_getting-started-windows-android.md index 7ea485b92d6..76e0cf6fe33 100644 --- a/docs/_getting-started-windows-android.md +++ b/docs/_getting-started-windows-android.md @@ -20,9 +20,13 @@ choco install -y nodejs-lts microsoft-openjdk17 If you have already installed Node on your system, make sure it is Node 18 or newer. If you already have a JDK on your system, we recommend JDK17. You may encounter problems using higher JDK versions. -> You can find additional installation options on [Node's Downloads page](https://nodejs.org/en/download/). +:::note +You can find additional installation options on [Node's Downloads page](https://nodejs.org/en/download/). +::: -> If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to `{project root folder}\android\gradle\wrapper\gradle-wrapper.properties` and changing the `distributionUrl` value to upgrade the Gradle version. You can check out [here the latest releases of Gradle](https://gradle.org/releases/). +:::info +If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to `{project root folder}\android\gradle\wrapper\gradle-wrapper.properties` and changing the `distributionUrl` value to upgrade the Gradle version. You can check out [here the latest releases of Gradle](https://gradle.org/releases/). +:::

Android development environment

@@ -39,7 +43,9 @@ Setting up your development environment can be somewhat tedious if you're new to Then, click "Next" to install all of these components. -> If the checkboxes are grayed out, you will have a chance to install these components later on. +:::note +If the checkboxes are grayed out, you will have a chance to install these components later on. +::: Once setup has finalized and you're presented with the Welcome screen, proceed to the next step. @@ -51,7 +57,9 @@ To do that, open Android Studio, click on "More Actions" button and select "SDK ![Android Studio Welcome](/docs/assets/GettingStartedAndroidStudioWelcomeWindows.png) -> The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +:::tip +The SDK Manager can also be found within the Android Studio "Settings" dialog, under **Languages & Frameworks** → **Android SDK**. +::: Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the `Android 15 (VanillaIceCream)` entry, then make sure the following items are checked: @@ -120,7 +128,9 @@ If you use Android Studio to open `./AwesomeProject/android`, you can see the li If you have recently installed Android Studio, you will likely need to [create a new AVD](https://developer.android.com/studio/run/managing-avds.html). Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the **VanillaIceCream** API Level 35 image. -> If you don't have HAXM installed, click on "Install HAXM" or follow [these instructions](https://github.com/intel/haxm/wiki/Installation-Instructions-on-Windows) to set it up, then go back to the AVD Manager. +:::note +If you don't have HAXM installed, click on "Install HAXM" or follow [these instructions](https://github.com/intel/haxm/wiki/Installation-Instructions-on-Windows) to set it up, then go back to the AVD Manager. +::: Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it. diff --git a/docs/_remove-global-cli.md b/docs/_remove-global-cli.md index 08d0d9ba3c1..022ba6de2f6 100644 --- a/docs/_remove-global-cli.md +++ b/docs/_remove-global-cli.md @@ -1,5 +1,8 @@ -> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues: -> -> ```shell -> npm uninstall -g react-native-cli @react-native-community/cli -> ``` +:::warning +If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues: + +```shell +npm uninstall -g react-native-cli @react-native-community/cli +``` + +::: diff --git a/docs/flatlist.md b/docs/flatlist.md index 6c299ca26bb..9cd965f1156 100644 --- a/docs/flatlist.md +++ b/docs/flatlist.md @@ -640,7 +640,9 @@ Set this true while waiting for new data from a refresh. This may improve scroll performance for large lists. On Android the default value is `true`. -> Note: May have bugs (missing content) in some circumstances - use at your own risk. +:::warning +May have bugs (missing content) in some circumstances - use at your own risk. +::: | Type | | ------- | @@ -787,7 +789,9 @@ scrollToIndex: (params: { Scrolls to the item at the specified index such that it is positioned in the viewable area such that `viewPosition` 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle. -> Note: Cannot scroll to locations outside the render window without specifying the `getItemLayout` prop. +:::note +Cannot scroll to locations outside the render window without specifying the `getItemLayout` prop. +::: **Parameters:** @@ -816,7 +820,9 @@ scrollToItem(params: { Requires linear scan through data - use `scrollToIndex` instead if possible. -> Note: Cannot scroll to locations outside the render window without specifying the `getItemLayout` prop. +:::note +Cannot scroll to locations outside the render window without specifying the `getItemLayout` prop. +::: **Parameters:** diff --git a/docs/legacy/native-modules-android.md b/docs/legacy/native-modules-android.md index 19126bbe58e..3835a202687 100644 --- a/docs/legacy/native-modules-android.md +++ b/docs/legacy/native-modules-android.md @@ -77,9 +77,11 @@ class CalendarModule(reactContext: ReactApplicationContext) : ReactContextBaseJa As you can see, your `CalendarModule` class extends the `ReactContextBaseJavaModule` class. For Android, Java/Kotlin native modules are written as classes that extend `ReactContextBaseJavaModule` and implement the functionality required by JavaScript. -> It is worth noting that technically Java/Kotlin classes only need to extend the `BaseJavaModule` class or implement the `NativeModule` interface to be considered a Native Module by React Native. +:::note +It is worth noting that technically Java/Kotlin classes only need to extend the `BaseJavaModule` class or implement the `NativeModule` interface to be considered a Native Module by React Native. -> However we recommend that you use `ReactContextBaseJavaModule`, as shown above. `ReactContextBaseJavaModule` gives access to the `ReactApplicationContext` (RAC), which is useful for Native Modules that need to hook into activity lifecycle methods. Using `ReactContextBaseJavaModule` will also make it easier to make your native module type-safe in the future. For native module type-safety, which is coming in future releases, React Native looks at each native module's JavaScript spec and generates an abstract base class that extends `ReactContextBaseJavaModule`. +However we recommend that you use `ReactContextBaseJavaModule`, as shown above. `ReactContextBaseJavaModule` gives access to the `ReactApplicationContext` (RAC), which is useful for Native Modules that need to hook into activity lifecycle methods. Using `ReactContextBaseJavaModule` will also make it easier to make your native module type-safe in the future. For native module type-safety, which is coming in future releases, React Native looks at each native module's JavaScript spec and generates an abstract base class that extends `ReactContextBaseJavaModule`. +::: ### Module Name @@ -267,7 +269,9 @@ class MyAppPackage : ReactPackage { This file imports the native module you created, `CalendarModule`. It then instantiates `CalendarModule` within the `createNativeModules()` function and returns it as a list of `NativeModules` to register. If you add more native modules down the line, you can also instantiate them and add them to the list returned here. -> It is worth noting that this way of registering native modules eagerly initializes all native modules when the application starts, which adds to the startup time of an application. You can use [TurboReactPackage](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/TurboReactPackage.java) as an alternative. Instead of `createNativeModules`, which return a list of instantiated native module objects, TurboReactPackage implements a `getModule(String name, ReactApplicationContext rac)` method that creates the native module object, when required. TurboReactPackage is a bit more complicated to implement at the moment. In addition to implementing a `getModule()` method, you have to implement a `getReactModuleInfoProvider()` method, which returns a list of all the native modules the package can instantiate along with a function that instantiates them, example [here](https://github.com/facebook/react-native/blob/8ac467c51b94c82d81930b4802b2978c85539925/ReactAndroid/src/main/java/com/facebook/react/CoreModulesPackage.java#L86-L165). Again, using TurboReactPackage will allow your application to have a faster startup time, but it is currently a bit cumbersome to write. So proceed with caution if you choose to use TurboReactPackages. +:::note +It is worth noting that this way of registering native modules eagerly initializes all native modules when the application starts, which adds to the startup time of an application. You can use [TurboReactPackage](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/TurboReactPackage.java) as an alternative. Instead of `createNativeModules`, which return a list of instantiated native module objects, TurboReactPackage implements a `getModule(String name, ReactApplicationContext rac)` method that creates the native module object, when required. TurboReactPackage is a bit more complicated to implement at the moment. In addition to implementing a `getModule()` method, you have to implement a `getReactModuleInfoProvider()` method, which returns a list of all the native modules the package can instantiate along with a function that instantiates them, example [here](https://github.com/facebook/react-native/blob/8ac467c51b94c82d81930b4802b2978c85539925/ReactAndroid/src/main/java/com/facebook/react/CoreModulesPackage.java#L86-L165). Again, using TurboReactPackage will allow your application to have a faster startup time, but it is currently a bit cumbersome to write. So proceed with caution if you choose to use TurboReactPackages. +::: To register the `CalendarModule` package, you must add `MyAppPackage` to the list of packages returned in ReactNativeHost's `getPackages()` method. Open up your `MainApplication.java` or `MainApplication.kt` file, which can be found in the following path: `android/app/src/main/java/com/your-app-name/`. @@ -431,7 +435,9 @@ import CalendarModule from './CalendarModule'; CalendarModule.createCalendarEvent('foo', 'bar'); ``` -> This assumes that the place you are importing `CalendarModule` is in the same hierarchy as `CalendarModule.js`. Please update the relative import as necessary. +:::note +This assumes that the place you are importing `CalendarModule` is in the same hierarchy as `CalendarModule.js`. Please update the relative import as necessary. +::: ### Argument Types @@ -449,12 +455,14 @@ When a native module method is invoked in JavaScript, React Native converts the | ReadableMap | ReadableMap | Object | | ReadableArray | ReadableArray | Array | -> The following types are currently supported but will not be supported in TurboModules. Please avoid using them: -> -> - Integer Java/Kotlin -> ?number -> - Float Java/Kotlin -> ?number -> - int Java -> number -> - float Java -> number +:::info +The following types are currently supported but will not be supported in TurboModules. Please avoid using them: + +- Integer Java/Kotlin -> ?number +- Float Java/Kotlin -> ?number +- int Java -> number +- float Java -> number + ::: For argument types not listed above, you will need to handle the conversion yourself. For example, in Android, `Date` conversion is not supported out of the box. You can handle the conversion to the `Date` type within the native method yourself like so: @@ -524,7 +532,9 @@ console.log(DEFAULT_EVENT_NAME); Technically it is possible to access constants exported in `getConstants()` directly off the native module object. This will no longer be supported with TurboModules, so we encourage the community to switch to the above approach to avoid necessary migration down the line. -> That currently constants are exported only at initialization time, so if you change getConstants values at runtime it won't affect the JavaScript environment. This will change with Turbomodules. With Turbomodules, `getConstants()` will become a regular native module method, and each invocation will hit the native side. +:::note +That currently constants are exported only at initialization time, so if you change getConstants values at runtime it won't affect the JavaScript environment. This will change with Turbomodules. With Turbomodules, `getConstants()` will become a regular native module method, and each invocation will hit the native side. +::: ### Callbacks @@ -729,7 +739,9 @@ fun createCalendarEvent(name: String, location: String, promise: Promise) { -> Similar to callbacks, a native module method can either reject or resolve a promise (but not both) and can do so at most once. This means that you can either call a success callback or a failure callback, but not both, and each callback can only be invoked at most one time. A native module can, however, store the callback and invoke it later. +:::note +Similar to callbacks, a native module method can either reject or resolve a promise (but not both) and can do so at most once. This means that you can either call a success callback or a failure callback, but not both, and each callback can only be invoked at most one time. A native module can, however, store the callback and invoke it later. +::: The JavaScript counterpart of this method returns a Promise. This means you can use the `await` keyword within an async function to call it and wait for its result: diff --git a/docs/legacy/native-modules-ios.md b/docs/legacy/native-modules-ios.md index 62459527773..d0615e1d8cc 100644 --- a/docs/legacy/native-modules-ios.md +++ b/docs/legacy/native-modules-ios.md @@ -105,7 +105,9 @@ RCT_EXPORT_METHOD(createCalendarEvent:(NSString *)name location:(NSString *)loca } ``` -> Please note that the `RCT_EXPORT_METHOD` macro will not be necessary with TurboModules unless your method relies on RCT argument conversion (see argument types below). Ultimately, React Native will remove `RCT_EXPORT_MACRO,` so we discourage people from using `RCTConvert`. Instead, you can do the argument conversion within the method body. +:::note +Please note that the `RCT_EXPORT_METHOD` macro will not be necessary with TurboModules unless your method relies on RCT argument conversion (see argument types below). Ultimately, React Native will remove `RCT_EXPORT_MACRO,` so we discourage people from using `RCTConvert`. Instead, you can do the argument conversion within the method body. +::: Before you build out the `createCalendarEvent()` method’s functionality, add a console log in the method so you can confirm it has been invoked from JavaScript in your React Native application. Use the `RCTLog` APIs from React. Let’s import that header at the top of your file and then add the log call. @@ -259,7 +261,9 @@ import NativeCalendarModule from './NativeCalendarModule'; NativeCalendarModule.createCalendarEvent('foo', 'bar'); ``` -> Note this assumes that the place you are importing `CalendarModule` is in the same hierarchy as `NativeCalendarModule.js`. Please update the relative import as necessary. +:::note +This assumes that the place you are importing `CalendarModule` is in the same hierarchy as `NativeCalendarModule.js`. Please update the relative import as necessary. +::: ### Argument Types @@ -277,12 +281,14 @@ When a native module method is invoked in JavaScript, React Native converts the | RCTResponseSenderBlock, RCTResponseErrorBlock | Function (failure) | | RCTPromiseResolveBlock, RCTPromiseRejectBlock | Promise | -> The following types are currently supported but will not be supported in TurboModules. Please avoid using them. -> -> - Function (failure) -> RCTResponseErrorBlock -> - Number -> NSInteger -> - Number -> CGFloat -> - Number -> float +:::info +The following types are currently supported but will not be supported in TurboModules. Please avoid using them. + +- Function (failure) -> RCTResponseErrorBlock +- Number -> NSInteger +- Number -> CGFloat +- Number -> float + ::: For iOS, you can also write native module methods with any argument type that is supported by the `RCTConvert` class (see [RCTConvert](https://github.com/facebook/react-native/blob/main/packages/react-native/React/Base/RCTConvert.h) for details about what is supported). The RCTConvert helper functions all accept a JSON value as input and map it to a native Objective-C type or class. @@ -306,7 +312,9 @@ console.log(DEFAULT_EVENT_NAME); Technically, it is possible to access constants exported in `constantsToExport()` directly off the `NativeModule` object. This will no longer be supported with TurboModules, so we encourage the community to switch to the above approach to avoid necessary migration down the line. -> Note that the constants are exported only at initialization time, so if you change `constantsToExport()` values at runtime it won't affect the JavaScript environment. +:::note +The constants are exported only at initialization time, so if you change `constantsToExport()` values at runtime it won't affect the JavaScript environment. +::: For iOS, if you override `constantsToExport()` then you should also implement `+ requiresMainQueueSetup` to let React Native know if your module needs to be initialized on the main thread, before any JavaScript code executes. Otherwise you will see a warning that in the future your module may be initialized on a background thread unless you explicitly opt out with `+ requiresMainQueueSetup:`. If your module does not require access to UIKit, then you should respond to `+ requiresMainQueueSetup` with NO. @@ -325,7 +333,9 @@ RCT_EXPORT_METHOD(createCalendarEvent:(NSString *)title You can then invoke the callback in your native function, providing whatever result you want to pass to JavaScript in an array. Note that `RCTResponseSenderBlock` accepts only one argument - an array of parameters to pass to the JavaScript callback. Below you will pass back the ID of an event created in an earlier call. -> It is important to highlight that the callback is not invoked immediately after the native function completes—remember the communication is asynchronous. +:::info +It is important to highlight that the callback is not invoked immediately after the native function completes—remember the communication is asynchronous. +::: ```objectivec RCT_EXPORT_METHOD(createCalendarEvent:(NSString *)title location:(NSString *)location callback: (RCTResponseSenderBlock)callback) @@ -541,9 +551,9 @@ RCT_EXPORT_METHOD(doSomethingExpensive:(NSString *)param callback:(RCTResponseSe ``` -> Sharing dispatch queues between modules -> -> The `methodQueue` method will be called once when the module is initialized, and then retained by React Native, so there is no need to keep a reference to the queue yourself, unless you wish to make use of it within your module. However, if you wish to share the same queue between multiple modules then you will need to ensure that you retain and return the same queue instance for each of them. +:::info Sharing dispatch queues between modules +The `methodQueue` method will be called once when the module is initialized, and then retained by React Native, so there is no need to keep a reference to the queue yourself, unless you wish to make use of it within your module. However, if you wish to share the same queue between multiple modules then you will need to ensure that you retain and return the same queue instance for each of them. +::: ### Dependency Injection @@ -585,7 +595,9 @@ class CalendarModule: NSObject { } ``` -> It is important to use the `@objc` modifiers to ensure the class and functions are exported properly to the Objective-C runtime. +:::note +It is important to use the `@objc` modifiers to ensure the class and functions are exported properly to the Objective-C runtime. +::: Then create a private implementation file that will register the required information with React Native: @@ -609,10 +621,12 @@ For those of you new to Swift and Objective-C, whenever you [mix the two languag You can also use `RCT_EXTERN_REMAP_MODULE` and `_RCT_EXTERN_REMAP_METHOD` to alter the JavaScript name of the module or methods you are exporting. For more information see [`RCTBridgeModule`](https://github.com/facebook/react-native/blob/main/packages/react-native/React/Base/RCTBridgeModule.h). -> Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header. +:::note +Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header. +::: ### Reserved Method Names #### invalidate() -Native modules can conform to the [RCTInvalidating](https://github.com/facebook/react-native/blob/main/packages/react-native/React/Base/RCTInvalidating.h) protocol on iOS by implementing the `invalidate()` method. This method [can be invoked](https://github.com/facebook/react-native/blob/0.62-stable/ReactCommon/turbomodule/core/platform/ios/RCTTurboModuleManager.mm#L456) when the native bridge is invalidated (ie: on devmode reload). Please use this mechanism as necessary to do the required cleanup for your native module. +Native modules can conform to the [RCTInvalidating](https://github.com/facebook/react-native/blob/main/packages/react-native/React/Base/RCTInvalidating.h) protocol on iOS by implementing the `invalidate()` method. This method [can be invoked](https://github.com/facebook/react-native/blob/0.62-stable/ReactCommon/turbomodule/core/platform/ios/RCTTurboModuleManager.mm#L456) when the native bridge is invalidated (i.e.: on devmode reload). Please use this mechanism as necessary to do the required cleanup for your native module. diff --git a/docs/linking.md b/docs/linking.md index bbe9eeed040..48c0db2f633 100644 --- a/docs/linking.md +++ b/docs/linking.md @@ -38,7 +38,9 @@ If you want to enable deep links in your app, please read the below guide: -> For instructions on how to add support for deep linking on Android, refer to [Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links](https://developer.android.com/training/app-indexing/deep-linking.html#adding-filters). +:::info +For instructions on how to add support for deep linking on Android, refer to [Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links](https://developer.android.com/training/app-indexing/deep-linking.html#adding-filters). +::: If you wish to receive the intent in an existing instance of MainActivity, you may set the `launchMode` of MainActivity to `singleTask` in `AndroidManifest.xml`. See [``](https://developer.android.com/guide/topics/manifest/activity-element.html) documentation for more information. @@ -51,7 +53,8 @@ If you wish to receive the intent in an existing instance of MainActivity, you m -> **NOTE:** On iOS, you'll need to add the `LinkingIOS` folder into your header search paths as described in step 3 [here](linking-libraries-ios#step-3). If you also want to listen to incoming app links during your app's execution, you'll need to add the following lines to your `*AppDelegate.m`: +:::note +On iOS, you'll need to add the `LinkingIOS` folder into your header search paths as described in step 3 [here](linking-libraries-ios#step-3). If you also want to listen to incoming app links during your app's execution, you'll need to add the following lines to your `*AppDelegate.m`: @@ -107,6 +110,8 @@ override func application( +::: + @@ -577,28 +582,34 @@ The `Promise` will reject on Android if it was impossible to check if the URL ca | -------------------------------------------------------- | ------ | ---------------- | | url
Required
| string | The URL to open. | -> For web URLs, the protocol (`"http://"`, `"https://"`) must be set accordingly! - -> This method has limitations on iOS 9+. From [the official Apple documentation](https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl): -> -> - If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always resolve to `false`. If the user reinstalls or upgrades the app, iOS resets the limit. -> -> As of iOS 9, your app also needs to provide the `LSApplicationQueriesSchemes` key inside `Info.plist` or `canOpenURL()` will always resolve to `false`. - -> When targeting Android 11 (SDK 30) you must specify the intents for the schemes you want to handle in `AndroidManifest.xml`. A list of common intents can be found [here](https://developer.android.com/guide/components/intents-common). -> -> For example to handle `https` schemes the following needs to be added to your manifest: -> -> ``` -> -> -> -> -> -> -> -> -> ``` +:::note +For web URLs, the protocol (`"http://"`, `"https://"`) must be set accordingly! +::: + +:::warning +This method has limitations on iOS 9+. From [the official Apple documentation](https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl): + +- If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always resolve to `false`. If the user reinstalls or upgrades the app, iOS resets the limit. +- As of iOS 9, your app also needs to provide the `LSApplicationQueriesSchemes` key inside `Info.plist` or `canOpenURL()` will always resolve to `false`. + ::: + +:::info +When targeting Android 11 (SDK 30) you must specify the intents for the schemes you want to handle in `AndroidManifest.xml`. A list of common intents can be found [here](https://developer.android.com/guide/components/intents-common). + +For example to handle `https` schemes the following needs to be added to your manifest: + +``` + + + + + + + + +``` + +::: --- @@ -610,9 +621,13 @@ static getInitialURL(): Promise; If the app launch was triggered by an app link, it will give the link url, otherwise it will give `null`. -> To support deep linking on Android, refer https://developer.android.com/training/app-indexing/deep-linking.html#handling-intents +:::info +To support deep linking on Android, refer https://developer.android.com/training/app-indexing/deep-linking.html#handling-intents. +::: -> getInitialURL may return `null` when Remote JS Debugging is active. Disable the debugger to ensure it gets passed. +:::tip +`getInitialURL` may return `null` when Remote JS Debugging is active. Disable the debugger to ensure it gets passed. +::: --- @@ -644,11 +659,13 @@ The method returns a `Promise` object. If the user confirms the open dialog or t | -------------------------------------------------------- | ------ | ---------------- | | url
Required
| string | The URL to open. | -> This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check `canOpenURL()` first. - -> For web URLs, the protocol (`"http://"`, `"https://"`) must be set accordingly! +:::note +This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check `canOpenURL()` first. For web URLs, the protocol (`"http://"`, `"https://"`) must be set accordingly! +::: -> This method may behave differently in a simulator e.g. `"tel:"` links are not able to be handled in the iOS simulator as there's no access to the dialer app. +:::warning +This method may behave differently in a simulator e.g. `"tel:"` links are not able to be handled in the iOS simulator as there's no access to the dialer app. +::: --- diff --git a/docs/safeareaview.md b/docs/safeareaview.md index cb1db9fdeb0..7ea73238593 100644 --- a/docs/safeareaview.md +++ b/docs/safeareaview.md @@ -50,4 +50,6 @@ export default App; Inherits [View Props](view.md#props). -> As padding is used to implement the behavior of the component, padding rules in styles applied to a `SafeAreaView` will be ignored and can cause different results depending on the platform. See [#22211](https://github.com/facebook/react-native/issues/22211) for details. +:::note +As padding is used to implement the behavior of the component, padding rules in styles applied to a `SafeAreaView` will be ignored and can cause different results depending on the platform. See [#22211](https://github.com/facebook/react-native/issues/22211) for details. +::: diff --git a/docs/sectionlist.md b/docs/sectionlist.md index 6c7d8892691..a12374be1e2 100644 --- a/docs/sectionlist.md +++ b/docs/sectionlist.md @@ -327,9 +327,11 @@ Tells the list an interaction has occurred, which should trigger viewability cal scrollToLocation(params: SectionListScrollParams); ``` -Scrolls to the item at the specified `sectionIndex` and `itemIndex` (within the section) positioned in the viewable area such that `viewPosition` 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle. +Scrolls to the item at the specified `sectionIndex` and `itemIndex` (within the section) positioned in the viewable area such that `viewPosition` set to `0` places it at the top (and may be covered by a sticky header), `1` at the bottom, and `0.5` centered in the middle. -> Note: Cannot scroll to locations outside the render window without specifying the `getItemLayout` or `onScrollToIndexFailed` prop. +:::note +You cannot scroll to locations outside the render window without specifying the `getItemLayout` or `onScrollToIndexFailed` prop. +::: **Parameters:** diff --git a/docs/set-up-your-environment.md b/docs/set-up-your-environment.md index de82c388d81..222df1a4f39 100644 --- a/docs/set-up-your-environment.md +++ b/docs/set-up-your-environment.md @@ -15,7 +15,7 @@ import GuideMacOSIOS from './\_getting-started-macos-ios.md'; In this guide, you'll learn how to set up your environment, so that you can run your project with Android Studio and Xcode. This will allow you to develop with Android emulators and iOS simulators, build your app locally, and more. -:::note +:::info This guide requires Android Studio or Xcode. If you already have one of these programs installed, you should be able to get up and running within a few minutes. If they are not installed, you should expect to spend about an hour installing and configuring them.
diff --git a/docs/textinput.md b/docs/textinput.md index 56c8e9924a0..c196ac74557 100644 --- a/docs/textinput.md +++ b/docs/textinput.md @@ -610,7 +610,9 @@ Sets the maximum number of lines for a `TextInput`. Use it with multiline set to Callback that is called when the text input is blurred. -> Note: If you are attempting to access the `text` value from `nativeEvent` keep in mind that the resulting value you get can be `undefined` which can cause unintended errors. If you are trying to find the last value of TextInput, you can use the [`onEndEditing`](textinput#onendediting) event, which is fired upon completion of editing. +:::note +If you are attempting to access the `text` value from `nativeEvent` keep in mind that the resulting value you get can be `undefined` which can cause unintended errors. If you are trying to find the last value of TextInput, you can use the [`onEndEditing`](textinput#onendediting) event, which is fired upon completion of editing. +::: | Type | | -------------------------------------------------------- | @@ -1039,10 +1041,12 @@ Possible values for `textContentType` are: When using `textContentType` as `newPassword` on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for `PasswordRules` take a look to the [Apple Docs](https://developer.apple.com/password-rules/). -> If passwords generation dialog doesn't appear please make sure that: -> -> - AutoFill is enabled: **Settings** → **Passwords & Accounts** → toggle "On" the **AutoFill Passwords**, -> - iCloud Keychain is used: **Settings** → **Apple ID** → **iCloud** → **Keychain** → toggle "On" the **iCloud Keychain**. +:::tip +If passwords generation dialog doesn't appear please make sure that: + +- AutoFill is enabled: **Settings** → **Passwords & Accounts** → toggle "On" the **AutoFill Passwords**, +- iCloud Keychain is used: **Settings** → **Apple ID** → **iCloud** → **Keychain** → toggle "On" the **iCloud Keychain**. + ::: | Type | | ------ | diff --git a/docs/the-new-architecture/custom-cxx-types.md b/docs/the-new-architecture/custom-cxx-types.md index f0592ab26ee..94db3e21b3f 100644 --- a/docs/the-new-architecture/custom-cxx-types.md +++ b/docs/the-new-architecture/custom-cxx-types.md @@ -336,7 +336,7 @@ Now, we need to implement the `validateAddress` function in C++. First, we need 2. Open the `shared/NativeSampleModule.cpp` file and add the function implementation -```c++ title="NativeSampleModule.cpp (validateAddress implementation)" +```cpp title="NativeSampleModule.cpp (validateAddress implementation)" bool NativeSampleModule::validateAddress(jsi::Runtime &rt, jsi::Object input) { std::string street = input.getProperty(rt, "street").asString(rt).utf8(rt); int32_t number = input.getProperty(rt, "num").asNumber(); @@ -365,7 +365,7 @@ To test the code in the app, we have to modify the `App.tsx` file. 1. Open the `App.tsx` file. Remove the content of the `App()` function. 2. Replace the body of the `App()` function with the following code: -```ts title="App.tsx (App function body replacement)" +```tsx title="App.tsx (App function body replacement)" const [street, setStreet] = React.useState(''); const [num, setNum] = React.useState(''); const [isValidAddress, setIsValidAddress] = React.useState< diff --git a/docs/view.md b/docs/view.md index 046a63392be..0aa380b41be 100644 --- a/docs/view.md +++ b/docs/view.md @@ -29,7 +29,9 @@ const ViewBoxesWithColorAndText = () => { export default ViewBoxesWithColorAndText; ``` -> `View`s are designed to be used with [`StyleSheet`](style.md) for clarity and performance, although inline styles are also supported. +:::note +`View`s are designed to be used with [`StyleSheet`](style.md) for clarity and performance, although inline styles are also supported. +::: ### Synthetic Touch Events @@ -418,7 +420,9 @@ This defines how far a touch event can start away from the view. Typical interfa For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with `hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}` -> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. +:::note +The touch area never extends past the parent view bounds, and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. +::: | Type | | -------------------------------------------------------------------- | @@ -430,7 +434,9 @@ For example, if a touchable view has a height of 20 the touchable height can be Used to locate this view from native classes. Has precedence over `nativeID` prop. -> This disables the 'layout-only view removal' optimization for this view! +:::warning +This disables the 'layout-only view removal' optimization for this view! +::: | Type | | ------ | @@ -461,7 +467,9 @@ See the [Android `importantForAccessibility` docs](https://developer.android.com Used to locate this view from native classes. -> This disables the 'layout-only view removal' optimization for this view! +:::warning +This disables the 'layout-only view removal' optimization for this view! +::: | Type | | ------ | @@ -793,7 +801,9 @@ Supports the following values: Used to locate this view in end-to-end tests. -> This disables the 'layout-only view removal' optimization for this view! +:::warning +This disables the 'layout-only view removal' optimization for this view! +::: | Type | | ------ | diff --git a/website/blog/2020-07-06-version-0.63.md b/website/blog/2020-07-06-version-0.63.md index 4ac6e1859d3..0248d05df09 100644 --- a/website/blog/2020-07-06-version-0.63.md +++ b/website/blog/2020-07-06-version-0.63.md @@ -136,6 +136,8 @@ At the same time, we are dropping support for Node 8. [Its LTS maintenance cycle Thank you to the hundreds of contributors that helped make 0.63 possible! -> Special thanks to [Rick Hanlon](https://twitter.com/rickhanlonii) for authoring the section on `LogBox` and [Eli White](https://twitter.com/Eli_White) for authoring the `Pressable` part of this article. +::note +Special thanks to [Rick Hanlon](https://twitter.com/rickhanlonii) for authoring the section on `LogBox` and [Eli White](https://twitter.com/Eli_White) for authoring the `Pressable` part of this article. +::: To see all the updates, take a look at the [0.63 changelog](https://github.com/facebook/react-native/blob/main/CHANGELOG.md#v0630). diff --git a/website/blog/2022-03-15-an-update-on-the-new-architecture-rollout.md b/website/blog/2022-03-15-an-update-on-the-new-architecture-rollout.md index 8222aef2e10..19a5e43073f 100644 --- a/website/blog/2022-03-15-an-update-on-the-new-architecture-rollout.md +++ b/website/blog/2022-03-15-an-update-on-the-new-architecture-rollout.md @@ -8,7 +8,9 @@ date: 2022-03-15 Hi everyone, [As previously announced](/blog/2022/01/21/react-native-h2-2021-recap#the-new-architecture-rollout-and-releases): -> 2022 is going to be the year of the New Architecture in open source +:::info +2022 is going to be the year of the New Architecture in open source. +::: If you still haven’t had the time to look into the New React Native Architecture (the Fabric Renderer and the TurboModule system), there is no better time to do it **than now**! diff --git a/website/blog/2023-06-21-package-exports-support.md b/website/blog/2023-06-21-package-exports-support.md index 6e9279898b4..db9ed4b1b31 100644 --- a/website/blog/2023-06-21-package-exports-support.md +++ b/website/blog/2023-06-21-package-exports-support.md @@ -61,9 +61,9 @@ import helpers from '@storybook/addon-actions/src/preset/addArgsHelpers'; The headlining features of Package Exports are: -- **Package encapsulation**: Only subpaths defined in `"exports"` can be imported from outside the package — giving packages control over their public API. +- **Package encapsulation**: Only subpaths defined in `"exports"` can be imported from outside the package — giving packages control over their public API. - **Subpath aliases**: Packages can define custom subpaths which map to a different file location (including via [subpath patterns](https://nodejs.org/docs/latest-v19.x/api/packages.html#subpath-patterns)) — allowing relocation of files while preserving the public API. -- **Conditional exports**: A subpath may resolve to a different underlying file depending on environment. For example, to target `"node"`, `"browser"`, or `"react-native"` runtimes — replacing the [`"browser"` field spec](https://github.com/defunctzombie/package-browser-field-spec). +- **Conditional exports**: A subpath may resolve to a different underlying file depending on environment. For example, to target `"node"`, `"browser"`, or `"react-native"` runtimes — replacing the [`"browser"` field spec](https://github.com/defunctzombie/package-browser-field-spec). :::note The full capabilities for `"exports"` are detailed in the [Node.js Package Entry Points spec](https://nodejs.org/docs/latest-v19.x/api/packages.html#package-entry-points). @@ -97,8 +97,8 @@ const config = { Metro exposes two further resolver options which configure how conditional exports behave: -- [`unstable_conditionNames`](https://metrobundler.dev/docs/configuration/#unstable_conditionnames-experimental) — The set of [condition names](https://nodejs.org/docs/latest-v19.x/api/packages.html#community-conditions-definitions) to assert when resolving conditional exports. By default, we match `['require', 'import', 'react-native']`. -- [`unstable_conditionsByPlatform`](https://metrobundler.dev/docs/configuration/#unstable_conditionsbyplatform-experimental) — The additional condition names to assert when resolving for a given platform target. By default, this matches `'browser'` when the platform is `'web'`. +- [`unstable_conditionNames`](https://metrobundler.dev/docs/configuration/#unstable_conditionnames-experimental) — The set of [condition names](https://nodejs.org/docs/latest-v19.x/api/packages.html#community-conditions-definitions) to assert when resolving conditional exports. By default, we match `['require', 'import', 'react-native']`. +- [`unstable_conditionsByPlatform`](https://metrobundler.dev/docs/configuration/#unstable_conditionsbyplatform-experimental) — The additional condition names to assert when resolving for a given platform target. By default, this matches `'browser'` when the platform is `'web'`. :::tip **Remember to use the React Native [Jest preset](https://github.com/facebook/react-native/blob/main/template/jest.config.js#L2)!** Jest includes support for Package Exports by default. In tests, you can override which `customExportConditions` are resolved using the [`testEnvironmentOptions`](https://jestjs.io/docs/configuration#testenvironmentoptions-object) option. @@ -146,7 +146,7 @@ If you are not using Yarn, substitute `yarn` for `npx` (or the relevant tool use We decided on an implementation of Package Exports in Metro that is spec-compliant (necessitating some breaking changes), but backwards compatible otherwise (helping apps with existing imports to migrate gradually). -The key breaking change is that when `"exports"` is provided by a package, it will be consulted first (before any other `package.json` fields) — and a matched subpath target will be used directly. +The key breaking change is that when `"exports"` is provided by a package, it will be consulted first (before any other `package.json` fields) — and a matched subpath target will be used directly. - Metro will not expand [`sourceExts`](https://metrobundler.dev/docs/configuration/#sourceexts) against the import specifier. - Metro will not resolve [platform-specific extensions](/docs/platform-specific-code) against the target file. @@ -187,7 +187,7 @@ In practice, we anticipate the main change for users will be the enforcement (vi ### Migrating to `"exports"` -**Adding an `"exports"` field to your package is entirely optional**. Existing package resolution features will behave identically for packages which don't use `"exports"` — and we have no plans to remove this behaviour. +**Adding an `"exports"` field to your package is entirely optional**. Existing package resolution features will behave identically for packages which don't use `"exports"` — and we have no plans to remove this behaviour. We believe that the new features of `"exports"` provide a compelling feature set for React Native package maintainers. @@ -204,11 +204,13 @@ If you decide to introduce `"exports"`, **we recommend making this as a breaking We've introduced `"react-native"` as a community condition (for use with conditional exports). This represents React Native, the framework, sitting alongside other recognised runtimes such as `"node"` and `"deno"` ([RFC](https://github.com/nodejs/node/pull/45367)). -> [Community Conditions Definitions — **`"react-native"`**](https://nodejs.org/docs/latest-v19.x/api/packages.html#community-conditions-definitions) -> -> _Will be matched by the React Native framework (all platforms). To target React Native for Web, "browser" should be specified before this condition._ +:::info +[Community Conditions Definitions — **`"react-native"`**](https://nodejs.org/docs/latest-v19.x/api/packages.html#community-conditions-definitions) + +_Will be matched by the React Native framework (all platforms). To target React Native for Web, "browser" should be specified before this condition._ +::: -This replaces the previous `"react-native"` root field. The priority order for how this was previously resolved was determined by projects, [which created ambiguity when using React Native for Web](https://github.com/expo/router/issues/37#issuecomment-1275925758). Under `"exports"`, _packages concretely define the resolution order for conditional entry points_ — removing this ambiguity. +This replaces the previous `"react-native"` root field. The priority order for how this was previously resolved was determined by projects, [which created ambiguity when using React Native for Web](https://github.com/expo/router/issues/37#issuecomment-1275925758). Under `"exports"`, _packages concretely define the resolution order for conditional entry points_ — removing this ambiguity. ```json "exports": {