@ -20,15 +20,23 @@ Please follow the steps below to prepare your development environment for React
1. **Install Node.js:** Please visit [Node.js downloads page](https://nodejs.org/en/download/) and download proper Node.js v20.11+ installer for your OS. An alternative is to install [NVM](https://github.com/nvm-sh/nvm) and use it to have multiple versions of Node.js in your operating system.
2. **[Optional] Install Yarn:** You may install Yarn v1 (not v2) following the instructions on [the installation page](https://classic.yarnpkg.com/en/docs/install). Yarn v1 delivers an arguably better developer experience compared to npm v6 and below. You may skip this step and work with npm, which is built-in in Node.js, instead.
3. **[Optional] Install VS Code:** [VS Code](https://code.visualstudio.com/) is a free, open-source IDE which works seamlessly with TypeScript. Although you can use any IDE including Visual Studio or Rider, VS Code will most likely deliver the best developer experience when it comes to React Native projects.
4. **Install an Emulator:** React Native applications need an Android emulator or an iOS simulator to run on your OS. See the [Android Studio Emulator](https://docs.expo.io/workflow/android-simulator/) or [iOS Simulator](https://docs.expo.io/workflow/ios-simulator/) on expo.io documentation to learn how to set up an emulator.
4. **Install an Emulator/Simulator:** React Native applications need an Android emulator or an iOS simulator to run on your OS. If you do not have Android Studio installed and configured on your system, we recommend [setting up android emulator without android studio](setting-up-android-emulator.md).
If you prefer the other way, you can check the [Android Studio Emulator](https://docs.expo.dev/workflow/android-studio-emulator/) or [iOS Simulator](https://docs.expo.dev/workflow/ios-simulator/) on expo.io documentation to learn how to set up an emulator.
## How to Start a New React Native Project
You have multiple options to initiate a new React Native project that works with ABP:
### 1. Using ABP CLI
### 1. Using ABP Studio
ABP Studio application is the most convenient and flexible way to initiate a React Native application based on ABP framework. You can follow the [tool documentation](../../../studio) and select the option below:
ABP CLI is probably the most convenient and flexible way to initiate an ABP solution with a React Native application. Simply [install the ABP CLI](../../../cli) and run the following command in your terminal:
ABP CLI is another way of creating an ABP solution with a React Native application. Simply [install the ABP CLI](../../../cli) and run the following command in your terminal:
```shell
abp new MyCompanyName.MyProjectName -csf -u <angularormvc> -m react-native
@ -38,33 +46,209 @@ abp new MyCompanyName.MyProjectName -csf -u <angular or mvc> -m react-native
This command will prepare a solution with an **Angular** or an **MVC** (depends on your choice), a **.NET Core**, and a **React Native** project in it.
### 2. Generating a CLI Command from Get Started Page
You can generate a CLI command on the [get started page of the abp.io website](https://abp.io/get-started). Then, use the command on your terminal to create a new [Startup Template](../../../solution-templates).
## How to Configure & Run the Backend
> React Native application does not trust the auto-generated .NET HTTPS certificate. You should use **HTTP** during the development.
> When you are using OpenIddict, You should remove 'clientSecret' on Environment.js (if exists) and disable "HTTPS-only" settings. (Openiddict has default since Version 6.0)
A React Native application running on an Android emulator or a physical phone **can not connect to the backend** on `localhost`. To fix this problem, it is necessary to run the backend application on your **local IP address**.
{{ if Tiered == "No"}}

- Open the `appsettings.json` file in the `.HttpApi.Host` folder. Replace the `localhost` address on the `SelfUrl` and `Authority` properties with your local IP address.
- Open the `launchSettings.json` file in the `.HttpApi.Host/Properties` folder. Replace the `localhost` address on the `applicationUrl` properties with your local IP address.
{{ else if Tiered == "Yes" }}

- Open the `appsettings.json` file in the `.AuthServer` folder. Replace the `localhost` address on the `SelfUrl` property with your local IP address.
- Open the `launchSettings.json` file in the `.AuthServer/Properties` folder. Replace the `localhost` address on the `applicationUrl` properties with your local IP address.
- Open the `appsettings.json` file in the `.HttpApi.Host` folder. Replace the `localhost` address on the `Authority` property with your local IP address.
- Open the `launchSettings.json` file in the `.HttpApi.Host/Properties` folder. Replace the `localhost` address on the `applicationUrl` properties with your local IP address.
A React Native application running on an Android emulator or a physical phone **can not connect to the backend** on `localhost`. To fix this problem, it is necessary to run the backend application using the `Kestrel` configuration.
- Open the `appsettings.json` file in the `.DbMigrator` folder. Replace the `localhost` address on the `RootUrl` property with your local IP address. Then, run the database migrator.
- Open the `appsettings.Development.json` file in the `.HttpApi.Host` folder. Add this configuration to accept global requests just to test the react native application on the development environment.
```json
{
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://0.0.0.0:44323" //replace with your host port
- Open the `appsettings.json` file in the `.DbMigrator` folder. Replace the `localhost` address on the `RootUrl` property with your local IP address. Then, run the database migrator.
- Open the `appsettings.Development.json` file in the `.AuthServer` folder. Add this configuration to accept global requests just to test the react native application on the development environment.
```json
{
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://0.0.0.0:44337"
}
}
}
}
```
- Open the `appsettings.Development.json` file in the `.HttpApi.Host` folder. Add this configuration to accept global requests again. In addition, you will need to introduce the authentication server as mentioned above.
```json
{
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://0.0.0.0:44389" //replace with your host port
}
}
},
"AuthServer": {
"Authority": "http://192.168.1.37:44337/", //replace with your IP and authentication port
"MetaAddress": "http://192.168.1.37:44337/",
"RequireHttpsMetadata": false,
"Audience": "MyTieredProject" //replace with your application name
- Open the `appsettings.Development.json` file in the `.AuthServer` folder. Add this configuration to accept global requests just to test the react native application on the development environment.
```json
{
"App": {
"EnablePII": true
},
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://0.0.0.0:44319"
}
}
}
}
```
- Open the `appsettings.Development.json` file in the `.AdministrationService` folder. Add this configuration to accept global requests just to test the react native application on the development environment. You should also provide the authentication server configuration. In addition, you need to apply the same process for all the services you would use in the react native application.
```json
{
"App": {
"EnablePII": true
},
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://0.0.0.0:44357"
}
}
},
"AuthServer": {
"Authority": "http://192.168.1.36:44319/",
"MetaAddress": "http://192.168.1.36:44319/",
"RequireHttpsMetadata": false,
"Audience": "AdministrationService"
}
}
```
- Update the `appsettings.json` file in the `.IdentityService` folder. Replace the `localhost` configuration with your local IP address for the react native application
```json
{
//...
"OpenIddict": {
"Applications": {
//...
"ReactNative": {
"RootUrl": "exp://192.168.1.36:19000"
},
"MobileGateway": {
"RootUrl": "http://192.168.1.36:44347/"
},
//...
},
//...
}
}
```
- Lastly, update the mobile gateway configurations as following:
Run the backend application as described in the [getting started document](../../../get-started).
@ -73,7 +257,7 @@ Run the backend application as described in the [getting started document](../..
## How to disable the Https-only settings of OpenIddict
Open the {{ if Tiered == "No" }}`MyProjectNameHttpApiHostModule`{{ else if Tiered == "Yes" }}`MyProjectNameAuthServerModule`{{ end }} project and copy-paste the below code-block to the `PreConfigureServices` method:
Open the {{ if Architecture == "Monolith" }}`MyProjectNameHttpApiHostModule`{{ if Architecture == "Tiered" }}`MyProjectNameAuthServerModule`{{ end }} project and copy-paste the below code-block to the `PreConfigureServices` method:
```csharp
#if DEBUG
@ -89,21 +273,27 @@ Open the {{ if Tiered == "No" }}`MyProjectNameHttpApiHostModule`{{ else if Tiere
1. Make sure the [database migration is complete](../../../get-started?UI=NG&DB=EF&Tiered=No#create-the-database) and the [API is up and running](../../../get-started?UI=NG&DB=EF&Tiered=No#run-the-application).
2. Open `react-native` folder and run `yarn` or `npm install` if you have not already.
3. Open the `Environment.js` in the `react-native` folder and replace the `localhost` address on the `apiUrl` and `issuer` properties with your local IP address as shown below:
3. Open the `Environment.ts` in the `react-native` folder and replace the `localhost` address on the `apiUrl` and `issuer` properties with your local IP address as shown below:
{{ if Architecture == "Monolith" }}


{{ if Tiered == "Yes" }}
{{ else if Architecture == "Tiered" }}

> Make sure that `issuer` matches the running address of the `.AuthServer` project, `apiUrl` matches the running address of the `.HttpApi.Host` or `.Web` project.
{{else}}
{{ else }}

> Make sure that `issuer` and `apiUrl` matches the running address of the `.HttpApi.Host` or `.Web` project.
> Make sure that `issuer`matches the running address of the `.AuthServer` project,`apiUrl` matches the running address of the `.AuthServer` project.
{{ end }}
4. Run `yarn start` or `npm start`. Wait for the Expo CLI to print the opitons.
1. Run `yarn start` or `npm start`. Wait for the Expo CLI to print the opitons.
> 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, while it has many features.
@ -113,14 +303,14 @@ In the above image, you can start the application with an Android emulator, an i
### Expo


### Android Studio
1. Start the emulator in **Android Studio** before running the `yarn start` or `npm start` command.
2. Press **a** to open in Android Studio.


Enter **admin** as the username and **1q2w3E\*** as the password to login to the application.
| `sdkmanager not found` | Make sure `PATH` includes the `latest/bin` directory |
| `x86_64 system image not found` | Make sure you've downloaded it using `sdkmanager` |
| `emulator not found` | Add the `emulator` directory to `PATH` |
| `setx` truncates path (Windows) | Use GUI to update environment variables manually |
---
## Summary
You can now run an Android emulator without installing Android Studio, entirely through the command line. This emulator can be used for React Native or any mobile development framework.
@ -242,6 +242,8 @@ You can use `admin` as username and `1q2w3E*` as default password to login to th
> Note: If you haven't selected a mobile framework, you can skip this step.
Before starting the mobile application, ensure that you have configured it for [react-native](../framework/ui/react-native) or [MAUI](../framework/ui/maui).
You can start the following application(s):
{{ if Tiered == "Yes" }}
@ -255,8 +257,7 @@ You can start the following application(s):
{{ else }}
- `Acme.BookStore.Web`
{{ end }}
Before starting the mobile application, ensure that you configure it for [react-native](../framework/ui/react-native) or [MAUI](../framework/ui/maui).
@ -94,22 +94,22 @@ You can follow [Mobile Application Development Tutorial - MAUI](../../tutorials/
This is the mobile application that is built based on Facebook's [React Native framework](https://reactnative.dev/) and [Expo](https://expo.dev/). It will be in the solution only if you've selected React Native as your mobile application option.
#### Project Structure
- **Environment.js**: file using for provide application level variables like `apiUrl`, `oAuthConfig` and etc.
- **Environment.ts**: file using for provide application level variables like `apiUrl`, `oAuthConfig` and etc.
- **api**: The `api` folder contains HTTP request files that simplify API management in the React Native starter template
- `API.js:` exports **axiosInstance**. It provides axios instance filled api url
- `API.ts:` exports **axiosInstance**. It provides axios instance filled api url
- **components**: In the `components` folder you can reach built in react native components that you can use in your app. These components **facilitates** your list, select and etc. operations
- **contexts**: `contexts` folder contains [react context](https://react.dev/reference/react/createContext). You can expots your contexts in this folder. `Localization context provided in here`
- **navigators**: folder contains [react-native stacks](https://reactnavigation.org/docs/stack-navigator/). After create new *FeatureName*Navigator we need to provide in `DrawerNavigator.js` file as `Drawer.Screen`
- **navigators**: folder contains [react-native stacks](https://reactnavigation.org/docs/stack-navigator/). After create new *FeatureName*Navigator we need to provide in `DrawerNavigator.tsx` file as `Drawer.Screen`
- **screens**: is the content of navigated page. We'll pass as component property to [Stack.Screen](https://reactnavigation.org/docs/native-stack-navigator/)
- **store**: folder manages state-management operations. We will define `actions`, `reducers`, `sagas` and `selectors` here.
- **store**: folder manages state-management operations. We will define `actions`, `listeners`, `reducers`, and `selectors` here.
- **styles**: folder contains app styles. `system-style.js` comes built in template we can also add new styles.
- **styles**: folder contains app styles. `system-style.ts` comes built in template we can also add new styles.
- **utils**: folder contains helper functions that we can use in application
@ -139,22 +139,28 @@ You can follow [Mobile Application Development Tutorial - MAUI](../../tutorials/
This is the mobile application that is built based on Facebook's [React Native framework](https://reactnative.dev/) and [Expo](https://expo.dev/). It will be in the solution only if you've selected React Native as your mobile application option.
#### Project Structure
- **Environment.js**: file using for provide application level variables like `apiUrl`, `oAuthConfig` and etc.
- **Environment.ts**: file using for providing application level variables like `apiUrl`, `oAuthConfig` and etc.
- **api**: The `api` folder contains HTTP request files that simplify API management in the React Native starter template
- `API.js:` exports **axiosInstance**. It provides axios instance filled api url
- `API.ts:` exports **axiosInstance**. It provides axios instance filled api url.
- **components**: In the `components` folder you can reach built in react native components that you can use in your app. These components **facilitates** your list, select and etc. operations
- **components**: In the `components` folder, you can reach built in react native components that you can use in your app. These components **facilitates** your list, select and etc. operations.
- **contexts**: `contexts` folder contains [react context](https://react.dev/reference/react/createContext). You can expots your contexts in this folder. `Localization context provided in here`
- **navigators**: folder contains [react-native stacks](https://reactnavigation.org/docs/stack-navigator/). After create new *FeatureName*Navigator we need to provide in `DrawerNavigator.js` file as `Drawer.Screen`
- **hocs**: this folder is added to contain higher order components. The purpose is to wrap components with additional features or properties. It initially has a `PermissionHoc.tsx` that wraps a component to check the permission grant status.
- **screens**: is the content of navigated page. We'll pass as component property to [Stack.Screen](https://reactnavigation.org/docs/native-stack-navigator/)
- **hooks**: covers the react native hooks where you can get a reference from [the official documentation](https://react.dev/reference/react/hooks).
- **store**: folder manages state-management operations. We will define `actions`, `reducers`, `sagas` and `selectors` here.
- **interceptors**: initializes a file called `APIInterceptor.ts` that has a function to manage the http operations in a better way.
- **styles**: folder contains app styles. `system-style.js` comes built in template we can also add new styles.
- **navigators**: folder contains [react-native stacks](https://reactnavigation.org/docs/stack-navigator/). After creating a new *FeatureName*Navigator we need to provide in `DrawerNavigator.ts` file as `Drawer.Screen`
- **screens**: folder has the content of navigated page. We will pass as component property to [Stack.Screen](https://reactnavigation.org/docs/native-stack-navigator/)
- **store**: folder manages state-management operations. We will define `actions`, `listeners`, `reducers`, and `selectors` here.
- **styles**: folder contains app styles. `system-style.ts` comes built in template we can also add new styles.
- **utils**: folder contains helper functions that we can use in application
@ -162,6 +168,6 @@ This is the mobile application that is built based on Facebook's [React Native f
React Native applications can't be run with the solution runner. You need to run them with the React Native CLI. You can check the [React Native documentation](https://reactnative.dev/docs/environment-setup) to learn how to setup the environment for React Native development.
Before running the React Native application, rest of the applications in the solution must be running. Such as AuthServer, MobileGateway and the microservices.
Before running the React Native application, the rest of the applications in the solution must be running. Such as AuthServer, MobileGateway and the microservices.
Then you can run the React Native application by following this documentation: [Getting Started with the React Native](../../framework/ui/react-native/index.md).
* `App.js` is the bootstrap component of the application.
* `Environment.js` file has the essential configuration of the application. `prod` and `dev` configurations are defined in this file.
* `App.tsx` is the bootstrap component of the application.
* `Environment.ts` file has the essential configuration of the application. `prod` and `dev` configurations are defined in this file.
* [Contexts](https://reactjs.org/docs/context.html) are created in the `src/contexts` folder.
* [Higher order components](https://reactjs.org/docs/higher-order-components.html) are created in the `src/hocs` folder.
* [Custom hooks](https://reactjs.org/docs/hooks-custom.html#extracting-a-custom-hook) are created in the `src/hooks`.
@ -353,12 +353,11 @@ Actions, reducers, sagas, selectors are created in the `src/store` folder. Store
* [**Store**](https://redux.js.org/basics/store) is defined in the `src/store/index.js` file.
* [**Actions**](https://redux.js.org/basics/actions/) are payloads of information that send data from your application to your store.
* [**Reducers**](https://redux.js.org/basics/reducers) specify how the application's state changes in response to actions sent to the store.
* [**Redux-Saga**](https://redux-saga.js.org/) is a library that aims to make application side effects (i.e. asynchronous things like data fetching and impure things like accessing the browser cache) easier to manage. Sagas are created in the `src/store/sagas` folder.
* [**Reselect**](https://github.com/reduxjs/reselect) library is used to create memoized selectors. Selectors are created in the `src/store/selectors` folder.
### APIs
[Axios](https://github.com/axios/axios) is used as the HTTP client library. An Axios instance is exported from `src/api/API.js` file to make HTTP calls with the same config. `src/api` folder also has the API files that have been created for API calls.
[Axios](https://github.com/axios/axios) is used as the HTTP client library. An Axios instance is exported from `src/api/API.ts` file to make HTTP calls with the same config. `src/api` folder also has the API files that have been created for API calls.
### Theming
@ -381,7 +380,6 @@ See the [Testing Overview](https://reactjs.org/docs/testing.html) document.
* [Axios](https://github.com/axios/axios) is used as HTTP client library.
* [Redux](https://redux.js.org/) is used as state management library.
* [Redux Toolkit](https://redux-toolkit.js.org/) library is used as a toolset for efficient Redux development.
* [Redux-Saga](https://redux-saga.js.org/) is used to manage asynchronous processes.
* [Redux Persist](https://github.com/rt2zz/redux-persist) is used for state persistance.
* [Reselect](https://github.com/reduxjs/reselect) is used to create memoized selectors.
* [i18n-js](https://github.com/fnando/i18n-js) is used as i18n library.