+
+
+
+
+Modern template — on the Application Type step, enable Mobile Application (React Native with Expo).
+
+
+
-React Native option
+
+Classic template — on the Mobile Framework step, select React Native.
+
+
## How to Prepare Development Environment
Please follow the steps below to prepare your development environment for React Native.
@@ -27,10 +32,8 @@ Please follow the steps below to prepare your development environment for React
1. **Install Node.js:** Visit the [Node.js downloads page](https://nodejs.org/en/download/) and download the appropriate Node.js v20.11+ installer for your operating system. Alternatively, you can install [NVM](https://github.com/nvm-sh/nvm) to manage multiple versions of Node.js on your system.
2. **[Optional] Install Yarn:** You can install Yarn v1 (not v2) by following the instructions on [the installation page](https://classic.yarnpkg.com/en/docs/install). Yarn v1 provides a better developer experience compared to npm v6 and below. You can skip this step and use npm, which is built into Node.js.
3. **[Optional] Install VS Code:** [VS Code](https://code.visualstudio.com/) is a free, open-source IDE that works seamlessly with TypeScript. While you can use any IDE, including Visual Studio or Rider, VS Code typically provides the best developer experience for React Native projects.
-4. **[Optional] Install an Emulator/Simulator:** If you want to test on Android emulators or iOS simulators (instead of using the Web View method), you'll need to install one of the following:
- - **Android Studio & Emulator:** Install [Android Studio](https://developer.android.com/studio) and set up an Android Virtual Device (AVD) through the AVD Manager. You can follow the [Android Studio Emulator guide](https://docs.expo.dev/workflow/android-studio-emulator/) on expo.io documentation.
- - **Xcode & iOS Simulator:** On macOS, install [Xcode](https://developer.apple.com/xcode/) from the App Store, which includes the iOS Simulator. You can follow the [iOS Simulator guide](https://docs.expo.dev/workflow/ios-simulator/) on expo.io documentation.
- > **Note:** The Web View method (recommended for quick testing) doesn't require an emulator or simulator. If you prefer a CLI-based approach for Android, you can check the [setting up android emulator without android studio](setting-up-android-emulator.md) guide as an alternative.
+
+Additional tools depend on how you plan to run the app — see the [Run the application](#run-the-application) section below.
## How to Start a New React Native Project
@@ -38,9 +41,21 @@ You have multiple options to initiate a new React Native project that works with
### 1. Using ABP Studio
-ABP Studio is the most convenient and flexible way to create a React Native application based on the ABP framework. Follow the [tool documentation](../../../studio) and select the option below:
+ABP Studio is the most convenient and flexible way to create a React Native application based on the ABP framework. Follow the [tool documentation](../../../studio) and select the mobile option in the solution wizard:
+
+
+Modern template — on the Application Type step, enable Mobile Application (React Native with Expo).
+
+Classic template — on the Mobile Framework step, select React Native.
+
-
-Enter **admin** as the username and **1q2w3E** as the password to log in to the application.
-
-The application is up and running. You can continue to develop your application based on this startup template.
+- User name: **admin**
+- Password: **1q2w3E\***
## Navigation
The startup template ships with **two navigation styles**, switchable when the project is created:
-- **Bottom Tab** — *the default* — three tabs at the bottom of the screen: **Home**, **Settings** and **Account**.
+- **Bottom Tab** — _the default_ — three tabs at the bottom of the screen: **Home**, **Settings** and **Account**.
- **Drawer** — a side menu (hamburger) with two items: **Home** and **Settings**.
-
Every main tab or drawer item is wired to **its own** native stack (`@react-navigation/native-stack`). Pushing more screens stays on that branch: the Back stack belongs to that tab or drawer route and does not mix with others. Bottom Tab and Drawer use the **same screen components**; they differ in how those screens are grouped and opened from the outer shell (and where the sign‑in/sign‑up flow lives in Bottom Tab versus Drawer).
-> **How to choose:** The mode is selected in **ABP Studio** during the *Mobile Framework* step. Switching modes after the project is generated is not a one-line change — you would need to add the missing navigator (and its `@react-navigation/drawer` or `@react-navigation/bottom-tabs` dependency) manually, then update `src/AppContainer.tsx` and `src/navigators/types.ts` to match. Pick the mode upfront when possible.
+> **How to choose:** The mode is selected in **ABP Studio** during the _Mobile Framework_ step. Switching modes after the project is generated is not a one-line change — you would need to add the missing navigator (and its `@react-navigation/drawer` or `@react-navigation/bottom-tabs` dependency) manually, then update `src/AppContainer.tsx` and `src/navigators/types.ts` to match. Pick the mode upfront when possible.
### Bottom Tab Navigation (default)
@@ -161,7 +116,7 @@ The root navigator is `BottomTabNavigator` (`src/navigators/BottomTabNavigator.t
- **HomeTab** → `HomeNavigator` → `HomeScreen` (hero greeting + feature cards).
- **SettingsTab** → `SettingsNavigator` → `SettingsScreen` (language, theme, profile/password shortcuts).
-- **AccountTab** → `AccountNavigator` — *conditional stack* based on the authentication state read from Redux:
+- **AccountTab** → `AccountNavigator` — _conditional stack_ based on the authentication state read from Redux:
- **Authenticated:** `AccountScreen` → `ChangePasswordScreen`, `ProfilePictureScreen`.
- **Guest:** `LoginScreen` → `RegisterScreen`, `ForgotPasswordScreen`, `ResetPasswordScreen`.
@@ -205,213 +160,6 @@ To add a screen to either navigation mode:
2. Register it as a `Stack.Screen` inside the appropriate navigator (e.g. `HomeNavigator`, `SettingsNavigator`, or `AccountNavigator`).
3. Add the route to the matching `*ParamList` in `src/navigators/types.ts` so the screen props stay typed.
-If the new screen needs to appear at the *root* level (a new tab or drawer item rather than a child of an existing stack), edit `BottomTabNavigator.tsx` or `DrawerNavigator.tsx` and update the corresponding `BottomTabParamList` / `RootDrawerParamList` type.
-
-## How to Configure & Run the Backend (Required for Emulator/Simulator Testing)
-
-> React Native application does not trust the auto-generated .NET HTTPS certificate. You should use **HTTP** during the development.
-
-To disable the HTTPS-only settings of OpenIddict, open the {{ if Architecture == "Monolith" }}`MyProjectNameHttpApiHostModule`{{ else if Architecture == "Tiered" }}`MyProjectNameAuthServerModule`{{ end }} project and add the following code block to the `PreConfigureServices` method:
-
-```csharp
-#if DEBUG
- PreConfigure
+
+See [Cloudflare tunnel (manual CLI)](#cloudflare-tunnel-manual-cli) below for what the tunnel script does, and [Automate Localhost Access for Expo](https://abp.io/community/articles/automate-localhost-access-for-expo-a-guide-to-dynamic-7cblqtj3) for architecture details and troubleshooting.
+
+{{ else if Architecture == "Tiered" }}
+
+> **Note:** The **MobileEmulator** run profile is available only for **Pro, non-tiered** solutions. For tiered architectures, follow [Manual Backend Configuration](./manual-backend-configuration.md) and the [manual CLI steps](#manual-cli-without-mobileemulator-profile) below.
+
+{{ else }}
+
+> **Note:** The **MobileEmulator** running profile is not included in the microservice template. Follow [Manual Backend Configuration](./manual-backend-configuration.md) and the [manual CLI steps](#manual-cli-without-mobileemulator-profile) below.
+
+{{ end }}
+
+## Cloudflare tunnel (manual CLI)
+
+{{ if Architecture == "Monolith" }}
+
+Non-tiered React Native templates ship with a Cloudflare tunnel automation script. The tunnel gives your mobile app a temporary **HTTPS** URL (for example `https://example.trycloudflare.com`) that forwards to your local backend — without reconfiguring Kestrel or OpenIddict over HTTP.
+
+The template includes:
+
+| Item | Location |
+| ------------------ | ------------------------------------------------------ |
+| Tunnel script | `react-native/scripts/tunnel.js` |
+| npm script | `yarn tunnel:api` (runs `node scripts/tunnel.js`) |
+| Generated config | `react-native/tunnel-config.json` (created at runtime) |
+| Environment switch | Inline comments in `react-native/Environment.ts` |
+
+When `tunnel.js` runs, it:
+
+1. Starts `cloudflared tunnel --url https://localhost:{api-port}` (port matches your backend host).
+2. Captures the generated `*.trycloudflare.com` domain from the `cloudflared` output.
+3. Writes `tunnel-config.json` and updates the fallback value in `Environment.ts`.
+
+### Steps
+
+1. **Switch `Environment.ts` to tunnel mode.** Open `react-native/Environment.ts` and follow the inline comments:
+ - **Uncomment** the tunnel configuration block (the block that reads `tunnel-config.json`).
+ - **Comment out** the localhost `apiUrl` / `appUrl` constants.
+2. **Start the backend host** if it is not already running.
+3. **Start the tunnel** from the `react-native` folder:
+
+```bash
+yarn tunnel:api
+```
+
+Or:
+
+```bash
+npm run tunnel:api
+```
+
+Wait until the script prints `✓ Tunnel domain saved`.
+
+4. **Start Expo** in a separate terminal:
+
+```bash
+yarn start
+```
+
+5. Start your Android emulator, iOS simulator, or connect a physical device.
+
+> **With ABP Studio:** The **MobileEmulator** run profile performs steps 2–4 for you after you update `Environment.ts`.
+
+See [Automate Localhost Access for Expo](https://abp.io/community/articles/automate-localhost-access-for-expo-a-guide-to-dynamic-7cblqtj3) for OAuth redirect considerations, troubleshooting, and development-build guidance.
+
+If Cloudflare tunnels are unavailable, use [Manual Backend Configuration](./manual-backend-configuration.md) as a fallback.
+
+{{ else if Architecture == "Tiered" }}
+
+Tiered templates do not include `tunnel.js` or the `tunnel:api` script. Configure the backend using [Manual Backend Configuration](./manual-backend-configuration.md), or adapt the [Cloudflare tunnel guide](https://abp.io/community/articles/automate-localhost-access-for-expo-a-guide-to-dynamic-7cblqtj3) for your auth server and API host ports.
+
+{{ else }}
+
+Microservice templates do not include `tunnel.js` or the `tunnel:api` script. Configure the backend using [Manual Backend Configuration](./manual-backend-configuration.md), or adapt the [Cloudflare tunnel guide](https://abp.io/community/articles/automate-localhost-access-for-expo-a-guide-to-dynamic-7cblqtj3) for your auth server and mobile gateway ports.
+
+{{ end }}
+
+## Manual CLI (without MobileEmulator profile)
+
+{{ if Architecture == "Monolith" }}
+
+If you are not using the **MobileEmulator** profile, prefer the [Cloudflare tunnel workflow](#cloudflare-tunnel-manual-cli) above. Only use [Manual Backend Configuration](./manual-backend-configuration.md) when tunnels are unavailable.
+
+{{ else }}
+
+1. Configure the backend as described in [Manual Backend Configuration](./manual-backend-configuration.md).
+2. Open the `Environment.ts` file in the React Native folder and replace the `localhost` address in the `apiUrl` and `issuer` properties with your local IP address:
+
+{{ if Architecture == "Tiered" }}
+
+> Make sure that `issuer` matches the running address of the `.AuthServer` project, and `apiUrl` matches the running address of the `.HttpApi.Host` or `.Web` project.
+
+{{ else }}
+
+> Make sure that `issuer` matches the running address of the `.AuthServer` project, and `apiUrl` matches the running address of the mobile gateway.
+
+{{ end }}
+
+1. Run `yarn start`, `yarn android`, or `yarn ios`.
+
+{{ end }}
+
+> The React Native application was generated with [Expo](https://expo.io/). Expo is a set of tools built around React Native to help you quickly start an app, and it includes many features.
+
+
+
+You can start the application on an Android emulator, an iOS simulator, or a physical phone by scanning the QR code or by choosing the corresponding option in the Expo CLI.
+
+### Android Studio
+
+1. Start the emulator in **Android Studio** before running `yarn start`, `yarn android`, or `npm start`.
+2. Press **a** in the Expo CLI to open on Android.
+
+### iOS Simulator
+
+Enter **admin** as the username and **1q2w3E** as the password to log in to the application.
diff --git a/docs/en/framework/ui/react-native/running-on-web.md b/docs/en/framework/ui/react-native/running-on-web.md
new file mode 100644
index 0000000000..9607e6a901
--- /dev/null
+++ b/docs/en/framework/ui/react-native/running-on-web.md
@@ -0,0 +1,116 @@
+```json
+//[doc-seo]
+{
+ "Description": "Run your ABP React Native application in the browser using ABP Studio or Expo Web with local HTTPS."
+}
+```
+
+```json
+//[doc-params]
+{
+ "Architecture": ["Monolith", "Tiered", "Microservice"]
+}
+```
+
+```json
+//[doc-nav]
+{
+ "Previous": {
+ "Name": "Overview",
+ "Path": "framework/ui/react-native"
+ },
+ "Next": {
+ "Name": "Running on Device",
+ "Path": "framework/ui/react-native/running-on-device"
+ }
+}
+```
+
+# Running on Web
+
+Running the React Native app in a browser is the **fastest way to test** login, navigation, and API integrations. No emulator, Cloudflare tunnel, or manual backend configuration is required.
+
+## React Native project folder
+
+{{ if Architecture == "Microservice" }}
+
+- `apps/mobile/react-native/`
+
+{{ else }}
+
+- `react-native/`
+
+{{ end }}
+
+Install dependencies once with `yarn install` or `npm install` in that folder.
+
+## Using ABP Studio (Recommended)
+
+Solutions created with ABP Studio include a **Default** run profile in the [Solution Runner](../../../studio/running-applications).
+
+{{ if Architecture == "Monolith" }}
+
+
+
+{{ else if Architecture == "Tiered" }}
+
+
+
+{{ else }}
+
+
+
+{{ end }}
+
+### One-time setup: Initialize Solution
+
+Run the **Initialize Solution** task from the **Tasks** tab if you have not already. For React Native solutions, this task also creates local SSL certificates (`localhost.pem` and `localhost-key.pem`) in the React Native folder using [mkcert](https://github.com/FiloSottile/mkcert). These certificates are required by the **Default** profile's local SSL proxy.
+
+### Start the Default profile
+
+When you start the **Default** profile, ABP Studio runs these main application:
+
+1. The backend host
+2. **ReactNative.LocalSslProxy** — terminates HTTPS on **`https://localhost:8443`** and forwards to Expo Web on port `8081`
+3. **ReactNative** — runs `npx expo start --web` and opens **`https://localhost:8443`** in your browser
+
+The solution template already adds `https://localhost:8443` to backend **CorsOrigins** and **RedirectAllowedUrls**, so no manual backend configuration is required.
+
+{{ if Architecture != "Microservice" }}
+
+
+
+{{ end }}
+
+You can enter **admin** as the username and **1q2w3E** as the password to log in.
+
+## Manual setup (without ABP Studio)
+
+If you are not using ABP Studio, use Expo Web with a local HTTPS proxy as described in the [Expo local HTTPS development guide](https://docs.expo.dev/guides/local-https-development/).
+
+1. Navigate to the React Native folder and install dependencies if you have not already.
+2. Generate SSL certificates in the React Native folder:
+
+```bash
+mkcert localhost
+```
+
+3. Start Expo Web:
+
+```bash
+yarn web
+```
+
+4. In a separate terminal, start the local SSL proxy (port `8443` matches the ABP Studio Default profile):
+
+```bash
+npx local-ssl-proxy --source 8443 --target 8081 --cert localhost.pem --key localhost-key.pem
+```
+
+Alternatively, run `yarn create:local-proxy` and set `SOURCE_PORT=8443` if your template uses a different default port since it is safer.
+
+5. Open **`https://localhost:8443`** in your browser.
+
+## Next steps
+
+To test on an Android emulator, iOS simulator, or physical device, continue with [Running on Device](./running-on-device.md).
diff --git a/docs/en/framework/ui/react-native/setting-up-android-emulator.md b/docs/en/framework/ui/react-native/setting-up-android-emulator.md
index 495197a0da..963c6d5b92 100644
--- a/docs/en/framework/ui/react-native/setting-up-android-emulator.md
+++ b/docs/en/framework/ui/react-native/setting-up-android-emulator.md
@@ -5,6 +5,16 @@
}
```
+````json
+//[doc-nav]
+{
+ "Previous": {
+ "Name": "Running on Device",
+ "Path": "framework/ui/react-native/running-on-device"
+ }
+}
+````
+
# Setting Up Android Emulator Without Android Studio (Windows, macOS, Linux)
This guide walks you through installing and running an Android emulator **without Android Studio**, using only the **Android Command Line Tools**.
diff --git a/docs/en/images/react-native-app.gif b/docs/en/images/react-native-app.gif
new file mode 100644
index 0000000000..7cf95f932d
Binary files /dev/null and b/docs/en/images/react-native-app.gif differ
diff --git a/docs/en/images/rn-default-profile.png b/docs/en/images/rn-default-profile.png
new file mode 100644
index 0000000000..8a19cc46c2
Binary files /dev/null and b/docs/en/images/rn-default-profile.png differ
diff --git a/docs/en/images/rn-expo-qr.png b/docs/en/images/rn-expo-qr.png
new file mode 100644
index 0000000000..adcbe65847
Binary files /dev/null and b/docs/en/images/rn-expo-qr.png differ
diff --git a/docs/en/images/rn-microservice-default-profile.png b/docs/en/images/rn-microservice-default-profile.png
new file mode 100644
index 0000000000..4ada6e47f5
Binary files /dev/null and b/docs/en/images/rn-microservice-default-profile.png differ
diff --git a/docs/en/images/rn-mobileEmulator-profile.png b/docs/en/images/rn-mobileEmulator-profile.png
new file mode 100644
index 0000000000..88a4ea1391
Binary files /dev/null and b/docs/en/images/rn-mobileEmulator-profile.png differ
diff --git a/docs/en/images/rn-select-legacy.png b/docs/en/images/rn-select-legacy.png
new file mode 100644
index 0000000000..dd6423999c
Binary files /dev/null and b/docs/en/images/rn-select-legacy.png differ
diff --git a/docs/en/images/rn-select-modern.png b/docs/en/images/rn-select-modern.png
new file mode 100644
index 0000000000..4d989eebab
Binary files /dev/null and b/docs/en/images/rn-select-modern.png differ
diff --git a/docs/en/images/rn-tiered-default-profile.png b/docs/en/images/rn-tiered-default-profile.png
new file mode 100644
index 0000000000..5d068e7988
Binary files /dev/null and b/docs/en/images/rn-tiered-default-profile.png differ
diff --git a/docs/en/images/rn-web-studio.png b/docs/en/images/rn-web-studio.png
new file mode 100644
index 0000000000..96f546bd48
Binary files /dev/null and b/docs/en/images/rn-web-studio.png differ
diff --git a/docs/en/tutorials/mobile/react-native/index.md b/docs/en/tutorials/mobile/react-native/index.md
index 5e97b6274a..859c8b91a5 100644
--- a/docs/en/tutorials/mobile/react-native/index.md
+++ b/docs/en/tutorials/mobile/react-native/index.md
@@ -1,13 +1,13 @@
```json
//[doc-seo]
{
- "Description": "Learn how to develop a mobile application using React Native with the ABP Framework. Build the Acme.BookStore mobile UI on top of the modernized ABP React Native template (NativeWind v4 + Bottom Tab navigation)."
+ "Description": "Learn how to develop a mobile application using React Native with the ABP Framework. Build the Acme.BookStore mobile UI on top of the modernized ABP React Native template (NativeWind v4 + Bottom Tab navigation)."
}
```
# Mobile Application Development Tutorial - React Native
-The React Native mobile option is *available for* ***Team*** *or higher licenses*. If you don't have a commercial license, follow this article by downloading the source code of the sample application linked below.
+The React Native mobile option is _available for_ **_Team_** _or higher licenses_. If you don't have a commercial license, follow this article by downloading the source code of the sample application linked below.
## About This Tutorial
@@ -18,6 +18,16 @@ The React Native mobile option is *available for* ***Team*** *or higher licenses
- The mobile template was modernized in 2026: it now uses **NativeWind v4** (Tailwind CSS for React Native) for styling, **Bottom Tab navigation** by default, and the **Redux Toolkit** store with hook-based access (`useSelector` / `useDispatch`). The `connectToRedux` HOC, the `DrawerNavigator`, and the legacy `DataList`/`AbpSelect` components from earlier versions no longer ship with the template — this tutorial walks through building the new equivalents.
- Before starting, please make sure that the [React Native Development Environment](../../../framework/ui/react-native/index.md) is ready on your machine.
+## Running the Application
+
+Before implementing UI changes, run the `Acme.BookStore` mobile application and verify that login works:
+
+1. Open the solution in **ABP Studio** and run the **Initialize Solution** task once (creates SSL certificates and other one-time setup).
+2. For browser testing, follow [Running on Web](../../../framework/ui/react-native/running-on-web.md) — start the **Default** run profile; ABP Studio opens the app at **`https://localhost:8443`**.
+3. For an Android emulator or iOS simulator, follow [Running on Device](../../../framework/ui/react-native/running-on-device.md) — switch to the **MobileEmulator** run profile, update `react-native/Environment.ts`, and start the profile (or run `yarn tunnel:api` manually).
+
+See the [React Native overview](../../../framework/ui/react-native/index.md) for environment setup and project creation.
+
## Download the Source Code
You can use the following link to download the source code of the application described in this article:
@@ -1059,6 +1069,7 @@ function CreateUpdateBookForm({ submit, book, authors }: CreateUpdateBookFormPro
}}
/>
+
{/* Publish date modal */}