From 02aabc3919370f18cb6fb0a94fa11f9879c4af54 Mon Sep 17 00:00:00 2001 From: Simek Date: Tue, 12 Aug 2025 15:37:07 +0200 Subject: [PATCH 1/2] Guides: migrate blockquote notes to admonitions --- docs/building-for-tv.md | 4 +- docs/communication-android.md | 8 +++- docs/integration-with-android-fragment.md | 4 +- docs/intro-react.md | 36 ++++++++++++---- docs/introduction.md | 20 ++++++--- docs/libraries.md | 4 +- docs/network.md | 12 ++++-- docs/optimizing-javascript-loading.md | 2 +- docs/running-on-device.md | 42 ++++++++++++++----- docs/security.md | 20 ++++++--- docs/testing-overview.md | 38 +++++++++++------ docs/typescript.md | 4 +- .../contributing/how-to-contribute-code.md | 4 +- 13 files changed, 144 insertions(+), 54 deletions(-) diff --git a/docs/building-for-tv.md b/docs/building-for-tv.md index 2428dc6b712..71ed7a11f5b 100644 --- a/docs/building-for-tv.md +++ b/docs/building-for-tv.md @@ -6,4 +6,6 @@ hide_table_of_contents: true TV devices support has been implemented with the intention of making existing React Native applications work on Apple TV and Android TV, with few or no changes needed in the JavaScript code for the applications. -> **Deprecated.** TV support has moved to the [React Native for TV](https://github.com/react-native-tvos/react-native-tvos#readme) repository. Please see the _README_ there for information on projects for Apple TV or Android TV. +:::warning Deprecated +TV support has moved to the [React Native for TV](https://github.com/react-native-tvos/react-native-tvos#readme) repository. Please see the **README** there for information on projects for Apple TV or Android TV. +::: diff --git a/docs/communication-android.md b/docs/communication-android.md index e7108577837..f78dc84cf65 100644 --- a/docs/communication-android.md +++ b/docs/communication-android.md @@ -114,7 +114,9 @@ It is fine to update properties anytime. However, updates have to be performed o There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead. -> **_Note:_** Currently, JS function `componentWillUpdateProps` of the top level RN component will not be called after a prop update. However, you can access the new props in `componentDidMount` function. +:::info +Currently, JS function `componentWillUpdateProps` of the top level RN component will not be called after a prop update. However, you can access the new props in `componentDidMount` function. +::: ### Passing properties from React Native to native @@ -146,4 +148,6 @@ Events are powerful, because they allow us to change React Native components wit Native modules are Java/Kotlin classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in [this article](legacy/native-modules-android). -> **_Warning_**: All native modules share the same namespace. Watch out for name collisions when creating new ones. +:::warning +All native modules share the same namespace. Watch out for name collisions when creating new ones. +::: diff --git a/docs/integration-with-android-fragment.md b/docs/integration-with-android-fragment.md index ea086300342..39a3d918f66 100644 --- a/docs/integration-with-android-fragment.md +++ b/docs/integration-with-android-fragment.md @@ -33,7 +33,9 @@ This is required by React Native to handle the back button press event. Go into your host activity and make sure it implements the `DefaultHardwareBackBtnHandler` interface: -> **Deprecated.** `Activity.onBackPressed()` has been [deprecated]() since API level 33. Android 16 devices with apps targeting API level 36 this will [no longer be called](https://developer.android.com/about/versions/16/behavior-changes-16#predictive-back) and [OnBackPressedDispatcher](https://developer.android.com/reference/androidx/activity/OnBackPressedDispatcher) should be used instead. +:::warning Deprecated +`Activity.onBackPressed()` has been [deprecated]() since API level 33. Android 16 devices with apps targeting API level 36 this will [no longer be called](https://developer.android.com/about/versions/16/behavior-changes-16#predictive-back) and [OnBackPressedDispatcher](https://developer.android.com/reference/androidx/activity/OnBackPressedDispatcher) should be used instead. +::: diff --git a/docs/intro-react.md b/docs/intro-react.md index f30c4c037f1..8eb487be3ec 100644 --- a/docs/intro-react.md +++ b/docs/intro-react.md @@ -65,7 +65,9 @@ const Cat = () => { export default Cat; ``` -> This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This [handy cheatsheet on JavaScript imports and exports](https://medium.com/dailyjs/javascript-module-cheatsheet-7bd474f1d829) can help. +:::tip +This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This [handy cheatsheet on JavaScript imports and exports](https://medium.com/dailyjs/javascript-module-cheatsheet-7bd474f1d829) can help. +::: Now take a closer look at that `return` statement. `Hello, I am your cat!` is using a kind of JavaScript syntax that makes writing elements convenient: JSX. @@ -132,7 +134,9 @@ export default Cat; You can think of curly braces as creating a portal into JS functionality in your JSX! -> Because JSX is included in the React library, it won’t work if you don’t have `import React from 'react'` at the top of your file! +:::tip +Because JSX is included in the React library, it won’t work if you don’t have `import React from 'react'` at the top of your file! +::: ## Custom Components @@ -169,12 +173,16 @@ export default Cat; -> If you’re familiar with web development, `` and `` might remind you of HTML! You can think of them as the `
` and `

` tags of application development. +:::info +If you’re familiar with web development, `` and `` might remind you of HTML! You can think of them as the `

` and `

` tags of application development. +::: -> On Android, you usually put your views inside `LinearLayout`, `FrameLayout`, `RelativeLayout`, etc. to define how the view’s children will be arranged on the screen. In React Native, `View` uses Flexbox for its children’s layout. You can learn more in [our guide to layout with Flexbox](flexbox). +:::info +On Android, you usually put your views inside `LinearLayout`, `FrameLayout`, `RelativeLayout`, etc. to define how the view’s children will be arranged on the screen. In React Native, `View` uses Flexbox for its children’s layout. You can learn more in [our guide to layout with Flexbox](flexbox). +::: @@ -303,7 +311,9 @@ export default CatApp; `Image` has [many different props](image#props), including [`style`](image#style), which accepts a JS object of design and layout related property-value pairs. -> Notice the double curly braces `{{ }}` surrounding `style`‘s width and height. In JSX, JavaScript values are referenced with `{}`. This is handy if you are passing something other than a string as props, like an array or number: ``. However, JS objects are **_also_** denoted with curly braces: `{width: 200, height: 200}`. Therefore, to pass a JS object in JSX, you must wrap the object in **another pair** of curly braces: `{{width: 200, height: 200}}` +:::note +Notice the double curly braces `{{ }}` surrounding `style`‘s width and height. In JSX, JavaScript values are referenced with `{}`. This is handy if you are passing something other than a string as props, like an array or number: ``. However, JS objects are **_also_** denoted with curly braces: `{width: 200, height: 200}`. Therefore, to pass a JS object in JSX, you must wrap the object in **another pair** of curly braces: `{{width: 200, height: 200}}` +::: You can build many things with props and the Core Components [`Text`](text), [`Image`](image), and [`View`](view)! But to build something interactive, you’ll need state. @@ -311,7 +321,9 @@ You can build many things with props and the Core Components [`Text`](text), [`I While you can think of props as arguments you use to configure how components render, **state** is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory! -> As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time. +:::info +As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time. +::: The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state. @@ -415,7 +427,9 @@ const Cat = (props: CatProps) => { }; ``` -> You can use `useState` to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with `const [timesPetted, setTimesPetted] = useState(0)`! +:::tip +You can use `useState` to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with `const [timesPetted, setTimesPetted] = useState(0)`! +::: Calling `useState` does two things: @@ -445,7 +459,9 @@ Now, when someone presses the button, `onPress` will fire, calling the `setIsHun /> ``` -> You might’ve noticed that although `isHungry` is a [const](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/const), it is seemingly reassignable! What is happening is when a state-setting function like `setIsHungry` is called, its component will re-render. In this case the `Cat` function will run again—and this time, `useState` will give us the next value of `isHungry`. +:::info +You might’ve noticed that although `isHungry` is a [const](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/const), it is seemingly reassignable! What is happening is when a state-setting function like `setIsHungry` is called, its component will re-render. In this case the `Cat` function will run again—and this time, `useState` will give us the next value of `isHungry`. +::: Finally, put your cats inside a `Cafe` component: @@ -460,7 +476,9 @@ const Cafe = () => { }; ``` -> See the `<>` and `` above? These bits of JSX are [fragments](https://react.dev/reference/react/Fragment). Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like `View`. +:::info +See the `<>` and `` above? These bits of JSX are [fragments](https://react.dev/reference/react/Fragment). Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like `View`. +::: --- diff --git a/docs/introduction.md b/docs/introduction.md index cd807674a16..f7ebe0aeb5e 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -21,7 +21,9 @@ You can start here and read through these docs linearly like a book; or you can To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can [dive in](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [brush up](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript) at Mozilla Developer Network. -> While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth. +:::info +While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth. +::: ## Interactive examples @@ -49,7 +51,9 @@ export default YourApp; The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!" -> Optionally, if you want to set up a local development environment, [you can follow our guide to setting up your environment on your local machine](set-up-your-environment) and paste the code examples into your project. (If you are a web developer, you may already have a local environment set up for mobile browser testing!) +:::note +Optionally, if you want to set up a local development environment, [you can follow our guide to setting up your environment on your local machine](set-up-your-environment) and paste the code examples into your project. (If you are a web developer, you may already have a local environment set up for mobile browser testing!) +::: ## Developer Notes @@ -59,17 +63,23 @@ People from many different development backgrounds are learning React Native. Yo -> Android developers may be familiar with this concept. +:::info +Android developers may be familiar with this concept. +::: -> iOS developers may be familiar with this concept. +:::info +iOS developers may be familiar with this concept. +::: -> Web developers may be familiar with this concept. +:::info +Web developers may be familiar with this concept. +::: diff --git a/docs/libraries.md b/docs/libraries.md index 8713df32244..e7565d34631 100644 --- a/docs/libraries.md +++ b/docs/libraries.md @@ -16,7 +16,9 @@ React Native libraries are typically installed from the [npm registry](https://w If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation. -> 💡 The terms "library" and "package" are used interchangeably in the JavaScript community. +:::note +The terms "library" and "package" are used interchangeably in the JavaScript community. +::: ## Installing a Library diff --git a/docs/network.md b/docs/network.md index a9fbae15831..160c8e8d56f 100644 --- a/docs/network.md +++ b/docs/network.md @@ -181,9 +181,13 @@ export default App; -> By default, iOS 9.0 or later enforce App Transport Security (ATS). ATS requires any HTTP connection to use HTTPS. If you need to fetch from a cleartext URL (one that begins with `http`) you will first need to [add an ATS exception](integration-with-existing-apps.md#test-your-integration). If you know ahead of time what domains you will need access to, it is more secure to add exceptions only for those domains; if the domains are not known until runtime you can [disable ATS completely](publishing-to-app-store.md#1-enable-app-transport-security). Note however that from January 2017, [Apple's App Store review will require reasonable justification for disabling ATS](https://forums.developer.apple.com/thread/48979). See [Apple's documentation](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33) for more information. +:::info +By default, iOS 9.0 or later enforce App Transport Security (ATS). ATS requires any HTTP connection to use HTTPS. If you need to fetch from a cleartext URL (one that begins with `http`) you will first need to [add an ATS exception](integration-with-existing-apps.md#test-your-integration). If you know ahead of time what domains you will need access to, it is more secure to add exceptions only for those domains; if the domains are not known until runtime you can [disable ATS completely](publishing-to-app-store.md#1-enable-app-transport-security). Note however that from January 2017, [Apple's App Store review will require reasonable justification for disabling ATS](https://forums.developer.apple.com/thread/48979). See [Apple's documentation](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33) for more information. +::: -> On Android, as of API Level 28, clear text traffic is also blocked by default. This behaviour can be overridden by setting [`android:usesCleartextTraffic`](https://developer.android.com/guide/topics/manifest/application-element#usesCleartextTraffic) in the app manifest file. +:::tip +On Android, as of API Level 28, clear text traffic is also blocked by default. This behaviour can be overridden by setting [`android:usesCleartextTraffic`](https://developer.android.com/guide/topics/manifest/application-element#usesCleartextTraffic) in the app manifest file. +::: ## Using Other Networking Libraries @@ -207,7 +211,9 @@ request.open('GET', 'https://mywebsite.com/endpoint/'); request.send(); ``` -> The security model for XMLHttpRequest is different than on web as there is no concept of [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) in native apps. +:::warning Caution +The security model for XMLHttpRequest is different than on web as there is no concept of [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) in native apps. +::: ## WebSocket Support diff --git a/docs/optimizing-javascript-loading.md b/docs/optimizing-javascript-loading.md index 934f6680bbc..e12d8631832 100644 --- a/docs/optimizing-javascript-loading.md +++ b/docs/optimizing-javascript-loading.md @@ -175,7 +175,7 @@ See the documentation for [`getTransformOptions` in Metro](https://metrobundler. ## Advanced: Use random access module bundles (non-Hermes) -:::info +:::tip **Not supported when [using Hermes](#use-hermes).** Hermes bytecode is not compatible with the RAM bundle format, and provides the same (or better) performance in all use cases. ::: diff --git a/docs/running-on-device.md b/docs/running-on-device.md index 6420248f98e..2ea67d7ba7e 100644 --- a/docs/running-on-device.md +++ b/docs/running-on-device.md @@ -8,7 +8,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import con It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production. -:::info +:::tip If you used `create-expo-app` to set up your project, you can run your app on a device in Expo Go by scanning the QR code that is displayed when you run `npm start`. Refer to the Expo guide for [running your project on your device](https://docs.expo.dev/get-started/expo-go/) for more information. ::: @@ -70,9 +70,13 @@ yarn android -> If you get a "bridge configuration isn't available" error, see [Using adb reverse](running-on-device.md#method-1-using-adb-reverse-recommended). +:::note +If you get a "bridge configuration isn't available" error, see [Using adb reverse](running-on-device.md#method-1-using-adb-reverse-recommended). +::: -> Hint: You can also use the `React Native CLI` to generate and run a `release` build (e.g. from the root of your project: `yarn android --mode release`). +:::tip +You can also use the `React Native CLI` to generate and run a `release` build (e.g. from the root of your project: `yarn android --mode release`). +:::

Connecting to the development server

@@ -163,7 +167,9 @@ yarn android -> Hint: You can also use the `React Native CLI` to generate and run a `release` build (e.g. from the root of your project: `yarn android --mode release`). +:::tip +You can also use the `React Native CLI` to generate and run a `release` build (e.g. from the root of your project: `yarn android --mode release`). +:::

Connecting to the development server

@@ -299,9 +305,13 @@ yarn android -> If you get a "bridge configuration isn't available" error, see [Using adb reverse](running-on-device.md#method-1-using-adb-reverse-recommended). +:::note +If you get a "bridge configuration isn't available" error, see [Using adb reverse](running-on-device.md#method-1-using-adb-reverse-recommended). +::: -> Hint: You can also use the `React Native CLI` to generate and run a `release` build (e.g. from the root of your project: `yarn android --mode release`). +:::tip +You can also use the `React Native CLI` to generate and run a `release` build (e.g. from the root of your project: `yarn android --mode release`). +:::

Connecting to the development server

@@ -382,7 +392,9 @@ If everything is set up correctly, your device will be listed as the build targe ![](/docs/assets/RunningOnDeviceReady.png) -> If you run into any issues, please take a look at Apple's [Launching Your App on a Device](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/LaunchingYourApponDevices/LaunchingYourApponDevices.html#//apple_ref/doc/uid/TP40012582-CH27-SW4) docs. +:::note +If you run into any issues, please take a look at Apple's [Launching Your App on a Device](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/LaunchingYourApponDevices/LaunchingYourApponDevices.html#//apple_ref/doc/uid/TP40012582-CH27-SW4) docs. +:::

Connecting to the development server

@@ -392,11 +404,15 @@ You can also iterate quickly on a device using the development server. You only ### Troubleshooting -> If you have any issues, ensure that your Mac and device are on the same network and can reach each other. Many open wireless networks with captive portals are configured to prevent devices from reaching other devices on the network. You may use your device's Personal Hotspot feature in this case. You may also share your internet (Wi-Fi/Ethernet) connection from your Mac to your device via USB and connect to the bundler through this tunnel for very high transfer speeds. +:::tip +If you have any issues, ensure that your Mac and device are on the same network and can reach each other. Many open wireless networks with captive portals are configured to prevent devices from reaching other devices on the network. You may use your device's Personal Hotspot feature in this case. You may also share your internet (Wi-Fi/Ethernet) connection from your Mac to your device via USB and connect to the bundler through this tunnel for very high transfer speeds. +::: When trying to connect to the development server you might get a [red screen with an error](debugging.md#logbox) saying: -> Connection to `http://localhost:8081/debugger-proxy?role=client` timed out. Are you running node proxy? If you are running on the device, check if you have the right IP address in `RCTWebSocketExecutor.m`. +:::note +Connection to `http://localhost:8081/debugger-proxy?role=client` timed out. Are you running node proxy? If you are running on the device, check if you have the right IP address in `RCTWebSocketExecutor.m`. +::: To solve this issue check the following points. @@ -421,14 +437,18 @@ You have built a great app using React Native, and you are now itching to releas [//]: # 'Windows, iOS' -> A Mac is required in order to build your app for iOS devices. Alternatively, you can refer to our [environment setup guide](environment-setup) to learn how to build your app using Expo CLI, which will allow you to run your app using the Expo client app. +:::info +A Mac is required in order to build your app for iOS devices. Alternatively, you can refer to our [environment setup guide](environment-setup) to learn how to build your app using Expo CLI, which will allow you to run your app using the Expo client app. +::: [//]: # 'Linux, iOS' -> A Mac is required in order to build your app for iOS devices. Alternatively, you can refer to our [environment setup guide](environment-setup) to learn how to build your app using Expo CLI, which will allow you to run your app using the Expo client app. +:::info +A Mac is required in order to build your app for iOS devices. Alternatively, you can refer to our [environment setup guide](environment-setup) to learn how to build your app using Expo CLI, which will allow you to run your app using the Expo client app. +::: diff --git a/docs/security.md b/docs/security.md index 1af4b74f3e3..bf8ed1ff5d4 100644 --- a/docs/security.md +++ b/docs/security.md @@ -19,7 +19,9 @@ If you must have an API key or a secret to access some resource from your app, t **For persisted user data, choose the right type of storage based on its sensitivity.** As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app. -> **Persisted vs unpersisted** — persisted data is written to the device’s disk, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to disk—so there's no data to access! +:::info +**Persisted vs unpersisted** — persisted data is written to the device’s disk, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to disk—so there's no data to access! +::: ### Async Storage @@ -38,7 +40,9 @@ If you must have an API key or a secret to access some resource from your app, t -> Async Storage is the React Native equivalent of Local Storage from the web +:::note +Async Storage is the React Native equivalent of Local Storage from the web +::: @@ -64,7 +68,9 @@ In order to use iOS Keychain services or Android Secure Shared Preferences, you - [expo-secure-store](https://docs.expo.dev/versions/latest/sdk/securestore/) - [react-native-keychain](https://github.com/oblador/react-native-keychain) -> **Be mindful of unintentionally storing or exposing sensitive info.** This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics. +:::warning Caution +**Be mindful of unintentionally storing or exposing sensitive info.** This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics. +::: ## Authentication and Deep Linking @@ -105,7 +111,9 @@ This guarantees that only the application that triggered the initial authorizati A library to consider for native OAuth is [react-native-app-auth](https://github.com/FormidableLabs/react-native-app-auth). React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native [AppAuth-iOS](https://github.com/openid/AppAuth-iOS) and [AppAuth-Android](https://github.com/openid/AppAuth-Android) libraries and can support PKCE. -> React-native-app-auth can support PKCE only if your Identity Provider supports it. +:::note +`react-native-app-auth` can support PKCE only if your Identity Provider supports it. +::: ![OAuth2 with PKCE](/docs/assets/diagram_pkce.svg) @@ -119,7 +127,9 @@ Using https endpoints could still leave your data vulnerable to interception. Wi **SSL pinning** is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be. -> When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work. +:::warning Caution +When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work. +::: ## Summary diff --git a/docs/testing-overview.md b/docs/testing-overview.md index ae00c6269f1..a25b5bb455e 100644 --- a/docs/testing-overview.md +++ b/docs/testing-overview.md @@ -41,13 +41,17 @@ To make your app more testable, start by separating the view part of your app— Theoretically, you could go so far as to move all logic and data fetching out of your components. This way your components would be solely dedicated to rendering. Your state would be entirely independent of your components. Your app’s logic would work without any React components at all! -> We encourage you to further explore the topic of testable code in other learning resources. +:::tip +We encourage you to further explore the topic of testable code in other learning resources. +::: ## Writing Tests After writing testable code, it’s time to write some actual tests! The default template of React Native ships with [Jest](https://jestjs.io) testing framework. It includes a preset that's tailored to this environment so you can get productive without tweaking the configuration and mocks straight away—[more on mocks](#mocking) shortly. You can use Jest to write all types of tests featured in this guide. -> If you do test-driven development, you actually write tests first! That way, testability of your code is given. +:::note +If you do test-driven development, you actually write tests first! That way, testability of your code is given. +::: ### Structuring Tests @@ -87,7 +91,9 @@ The great thing about unit tests is that they are quick to write and run. Theref Sometimes, when your tested objects have external dependencies, you’ll want to “mock them out.” “Mocking” is when you replace some dependency of your code with your own implementation. -> Generally, using real objects in your tests is better than using mocks but there are situations where this is not possible. For example: when your JS unit test relies on a native module written in Java or Objective-C. +:::info +Generally, using real objects in your tests is better than using mocks but there are situations where this is not possible. For example: when your JS unit test relies on a native module written in Java or Objective-C. +::: Imagine you’re writing an app that shows the current weather in your city and you’re using some external service or other dependency that provides you with the weather information. If the service tells you that it’s raining, you want to show an image with a rainy cloud. You don’t want to call that service in your tests, because: @@ -97,7 +103,9 @@ Imagine you’re writing an app that shows the current weather in your city and Therefore, you can provide a mock implementation of the service, effectively replacing thousands of lines of code and some internet-connected thermometers! -> Jest comes with [support for mocking](https://jestjs.io/docs/en/mock-functions#mocking-modules) from function level all the way to module level mocking. +:::note +Jest comes with [support for mocking](https://jestjs.io/docs/en/mock-functions#mocking-modules) from function level all the way to module level mocking. +::: ## Integration Tests @@ -105,12 +113,14 @@ When writing larger software systems, individual pieces of it need to interact w In integration testing, real individual units are combined (same as in your app) and tested together to ensure that their cooperation works as expected. This is not to say that mocking does not happen here: you’ll still need mocks (for example, to mock communication with a weather service), but you'll need them much less than in unit testing. -> Please note that the terminology around what integration testing means is not always consistent. Also, the line between what is a unit test and what is an integration test may not always be clear. For this guide, your test falls into "integration testing" if it: -> -> - Combines several modules of your app as described above -> - Uses an external system -> - Makes a network call to other application (such as the weather service API) -> - Does any kind of file or database I/O +:::info +Please note that the terminology around what integration testing means is not always consistent. Also, the line between what is a unit test and what is an integration test may not always be clear. For this guide, your test falls into "integration testing" if it: + +- Combines several modules of your app as described above +- Uses an external system +- Makes a network call to other application (such as the weather service API) +- Does any kind of file or database I/O + ::: @@ -130,7 +140,9 @@ There are several libraries that can help you testing these: - [React Native Testing Library](https://callstack.github.io/react-native-testing-library/) builds on top of React’s test renderer and adds `fireEvent` and `query` APIs described in the next paragraph. - [Deprecated] React’s [Test Renderer](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#deprecated-react-test-renderer), developed alongside its core, provides a React renderer that can be used to render React components to pure JavaScript objects, without depending on the DOM or a native mobile environment. -> Component tests are only JavaScript tests running in Node.js environment. They do _not_ take into account any iOS, Android, or other platform code which is backing the React Native components. It follows that they cannot give you a 100% confidence that everything works for the user. If there is a bug in the iOS or Android code, they will not find it. +:::warning Caution +Component tests are only JavaScript tests running in Node.js environment. They do _not_ take into account any iOS, Android, or other platform code which is backing the React Native components. It follows that they cannot give you a 100% confidence that everything works for the user. If there is a bug in the iOS or Android code, they will not find it. +::: @@ -180,7 +192,9 @@ Conversely, you should avoid: Avoid testing implementation details like props or state—while such tests work, they are not oriented toward how users will interact with the component and tend to break by refactoring (for example when you'd like to rename some things or rewrite class component using hooks). -> React class components are especially prone to testing their implementation details such as internal state, props or event handlers. To avoid testing implementation details, prefer using function components with Hooks, which make relying on component internals _harder_. +:::info +React class components are especially prone to testing their implementation details such as internal state, props or event handlers. To avoid testing implementation details, prefer using function components with Hooks, which make relying on component internals _harder_. +::: Component testing libraries such as [React Native Testing Library](https://callstack.github.io/react-native-testing-library/) facilitate writing user-centric tests by careful choice of provided APIs. The following example uses `fireEvent` methods `changeText` and `press` that simulate a user interacting with the component and a query function `getAllByText` that finds matching `Text` nodes in the rendered output. diff --git a/docs/typescript.md b/docs/typescript.md index 00f885cd44f..1e959e32da7 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -52,7 +52,9 @@ This command adds the latest version of every dependency. The versions may need 3. Rename a JavaScript file to be `*.tsx` -> You should leave the `./index.js` entrypoint file as it is otherwise you may run into an issue when it comes to bundling a production build. +:::warning Caution +You should leave the `./index.js` entrypoint file as it is otherwise you may run into an issue when it comes to bundling a production build. +::: 4. Run `tsc` to type-check your new TypeScript files. diff --git a/website/contributing/how-to-contribute-code.md b/website/contributing/how-to-contribute-code.md index 1bcd51a35c2..4bff72313b0 100644 --- a/website/contributing/how-to-contribute-code.md +++ b/website/contributing/how-to-contribute-code.md @@ -4,8 +4,8 @@ title: How to Contribute Code Thank you for your interest in contributing to React Native! From commenting on and triaging issues, to reviewing and sending PRs, [all contributions are welcome](/contributing/overview). In this document, we'll cover the steps to contributing code to React Native. -If you are eager to start contributing code right away, we have a list of [`good first issues`](https://github.com/facebook/react-native/labels/good%20first%20issue) that contain bugs which have a relatively limited scope. -Issues labeled [`help wanted`](https://github.com/facebook/react-native/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22help+wanted+%3Aoctocat%3A%22+sort%3Aupdated-desc+) are good issues to submit a PR for. +If you are eager to start contributing code right away, we have a list of [`Good first issues`](https://github.com/facebook/react-native/labels/good%20first%20issue) that contain bugs which have a relatively limited scope. +Issues labeled [`Help wanted`](https://github.com/facebook/react-native/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22help+wanted+%3Aoctocat%3A%22+sort%3Aupdated-desc+) are good issues to submit a PR for. ## Prerequisites From ac918c2f31b367fa1f8e35b82d25f930e279945d Mon Sep 17 00:00:00 2001 From: Simek Date: Thu, 14 Aug 2025 08:42:51 +0200 Subject: [PATCH 2/2] apply review feedback --- docs/introduction.md | 2 +- docs/testing-overview.md | 2 +- docs/typescript.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index f7ebe0aeb5e..ba782cd838c 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -51,7 +51,7 @@ export default YourApp; The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!" -:::note +:::tip Optionally, if you want to set up a local development environment, [you can follow our guide to setting up your environment on your local machine](set-up-your-environment) and paste the code examples into your project. (If you are a web developer, you may already have a local environment set up for mobile browser testing!) ::: diff --git a/docs/testing-overview.md b/docs/testing-overview.md index a25b5bb455e..59562fae587 100644 --- a/docs/testing-overview.md +++ b/docs/testing-overview.md @@ -140,7 +140,7 @@ There are several libraries that can help you testing these: - [React Native Testing Library](https://callstack.github.io/react-native-testing-library/) builds on top of React’s test renderer and adds `fireEvent` and `query` APIs described in the next paragraph. - [Deprecated] React’s [Test Renderer](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#deprecated-react-test-renderer), developed alongside its core, provides a React renderer that can be used to render React components to pure JavaScript objects, without depending on the DOM or a native mobile environment. -:::warning Caution +:::warning Component tests are only JavaScript tests running in Node.js environment. They do _not_ take into account any iOS, Android, or other platform code which is backing the React Native components. It follows that they cannot give you a 100% confidence that everything works for the user. If there is a bug in the iOS or Android code, they will not find it. ::: diff --git a/docs/typescript.md b/docs/typescript.md index 1e959e32da7..3a056bcc9d0 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -52,7 +52,7 @@ This command adds the latest version of every dependency. The versions may need 3. Rename a JavaScript file to be `*.tsx` -:::warning Caution +:::warning You should leave the `./index.js` entrypoint file as it is otherwise you may run into an issue when it comes to bundling a production build. :::