@iterable/react-native-sdk/lib/react-native-dev/README.md

Iterable SDK for React Native.

# react-native-dev

The Dev App for internal React Native SDK.

## Prerequisite:

1. Install [yarn](https://classic.yarnpkg.com/en/docs/install/) if not installed.
2. Install [typescript](https://yarnpkg.com/package/typescript) if not installed.
3. Clone [react-native-dev](https://github.com/Iterable/react-native-dev)
   into a folder on your local machine(EG: see the `react` folder in the
   below folder structure).
4. Clone
   [react-native-sdk](https://github.com/Iterable/react-native-sdk).  The
   location of this library does not matter, but we suggest that it be a sibling
   of `react-native-dev`.
5. Clone [iterable-swift-sdk](https://github.com/Iterable/iterable-swift-sdk)
   into a folder named `ios` which should be adjacent to parent folder of
   above cloned projects.
6. Clone [iterable-android-sdk](https://github.com/Iterable/iterable-android-sdk)
   into a folder named `android` which should be adjacent to parent folder of
   above cloned projects.

Your project folder should look like this:
<pre>
|`YOUR_FOLDER`
|   |-> react
|   |   |-> <b>react-native-dev</b>
|   |   |-> <b>react-native-sdk</b> (suggested location)
|   |->iOS
|   |   |-> <b>iterable-swift-sdk</b>
|   |->android
|   |   |-> <b>iterable-android-sdk</b>
</pre>

## Configuring your local environment
### Testing with `npm pack`
1. cd into `react-native-sdk` folder
2. Run `yarn install`
3. Bump the version number in the package.json.  Any new pack needs a new
   version number to correctly update.
   - To bump local changes for testing, a common way to bump the version is to
     do `X.Y.Z-rc.1` where `X.Y.Z` is the version number of the last package,
     and `1` is the local version number.
4. Run `npm pack`
5. Copy the path to the generated package.  It should be something like this: */Users/John.Smith/mobile/RN/react-native-sdk/iterable-react-native-sdk-2.0.0-alpha-rc.11.tgz*
6. cd into `react-native-dev`
7. Run `yarn add [path to package]`.  EG: `yarn add /Users/John.Smith/mobile/RN/react-native-sdk/iterable-react-native-sdk-2.0.0-alpha-rc.11.tgz`
8. Run the steps for starting the dev app

### To test the package installation of `react-native-sdk` locally:
1. Install [verdaccio](https://verdaccio.org/docs/installation/)  by running:
  ```shell
    npm install -g verdaccio
  ```
2. Run `verdaccio` in the terminal
3. Run `npm adduser --registry http://localhost:4873` to add a user for
   publishing.  If you do not already have an npm account, you can create it
   now.
4. Bump the version number in the package.json for `react-native-sdk` if
   necessary.  Remember that any new publish needs a new version number -- even
   if you are just doing local testing.
   - To bump local changes for testing, a common way to bump the version is to
     do `X.Y.Z-rc.1` where `X.Y.Z` is the version number of the last package,
     and `1` is the local version number.
5. cd into the `react-native-sdk` folder
6. Run `npm publish --registry http://localhost:4873`
7. Open http://localhost:4873 in your browser -- you should see the package you
   just published.
8. cd into the `react-native-dev` folder
9. Run `yarn add --registry http://localhost:4873 @iterable/react-native-sdk`
10. Run the steps for starting the dev app

**IMPORTANT**: DO NOT commit the updated `package.json` file.  It will have an
incorrect link for the `react-native-sdk` package.

### To develop `iterable-swift-sdk` locally:
1. In the `react-native-dev` folder, open the `Podfile` file (found in the `ios`
   folder)
2. Uncomment the line reading `# pod 'Iterable-iOS-SDK', :path =>
   '../../../ios/iterable-swift-sdk'`
3. Comment out the line reading `pod 'Iterable-iOS-AppExtensions'`
4. Uncomment the line reading `# pod 'Iterable-iOS-AppExtensions', :path =>
   '../../../ios/iterable-swift-sdk'`
5. Run the steps for starting the dev app

**IMPORTANT**: DO NOT commit the `Podfile` with these changes.

### To develop `iterable-android-sdk` locally:
1. In the `react-native-dev` folder, open the `settings.gradle` file (found in
   the `android` folder)
2. Uncomment the line reading `// project(':iterableapi').projectDir = new
   File(settingsDir,'../../android/iterable-android-sdk/iterableapi')'`
3. Run the steps for starting the dev app

**IMPORTANT**: DO NOT commit the `settings.gradle` with these changes.

## 🏗️ React Native Architecture Toggle

This project includes a powerful system for toggling between React Native's legacy architecture and the new architecture (Fabric/TurboModules). This is essential for testing compatibility across both architectures.

### Quick Commands

```bash
# Enable new architecture
yarn arch:enable

# Disable new architecture (legacy)
yarn arch:disable

# Check current status
yarn arch:status

# Test the configuration
yarn arch:test
```

### How It Works

The toggle system automatically updates:
- **Environment Variables**: `.env.local` file with `ITBL_NEW_ARCH=true/false`
- **Android Configuration**: `android/gradle.properties` with `newArchEnabled=true/false`
- **iOS Configuration**: `ios/Podfile` with `RCT_NEW_ARCH_ENABLED=1/0`

### Visual Feedback

When using the legacy architecture, you'll see a red "LEGACY" banner at the top of the app to clearly indicate which architecture is active.

### Testing Both Architectures

1. **Test Legacy Architecture:**
   ```bash
   yarn arch:disable
   yarn android  # or yarn ios
   ```

2. **Test New Architecture:**
   ```bash
   yarn arch:enable
   yarn android  # or yarn ios
   ```

3. **Verify Configuration:**
   ```bash
   yarn arch:test  # Shows all configuration values
   ```

### Architecture Status Display

The `yarn arch:status` command shows:
```
🏗️  React Native Architecture Status
=====================================
Current setting:
   ✅ New Architecture: ENABLED (from .env.local)
   📄 gradle.properties: newArchEnabled=true
```

### Important Notes

- Always run `yarn clean:android` and `yarn clean:ios` after toggling architectures
- The system preserves your existing `.env.local` content when updating
- Environment variables take precedence: `.env.local` > `.env`
- The app will show a "LEGACY" banner when using the legacy architecture

## Starting the Dev App
1. cd into the `react-native-dev` folder
2. Run `yarn install`
3. cd into the `ios` folder
4. Run `bundle install`
5. Run `bundle exec pod install`
6. cd back to the `react-native-dev` folder
7. Run `yarn start`
8. Once the metro server has started, type `i` to open the app in the iOS
   simulator, or type `a` to open the app in the Android emulator.

### Android
If you are experiencing issues running, try the following:

1. Make sure [Android Studio](https://developer.android.com/studio) is installed
2. Make sure [adb](https://developer.android.com/tools/adb) is installed
   - You can check by running `which adb` in your terminal. If a path is given,
     then it exists on your machine
   - To download, run `brew install —-cask android-platform-tools`
3. Make sure that **Java version 11** is installed
   - To download, run `brew install --cask zulu@17`
4. In the root directory for this repo ('react-native-dev'), run `yarn start` / `npm start`
5. In another terminal, cd into the android directory for this repo `cd android`
6. Open Android Studio with the **android** folder as your root
   - You can either do this by manually opening Android Studio and selecting the
     project, or by running `open -a /Applications/Android\ Studio.app` in the
     **android** directory.
7. Sync the project
   - You can do this by either:
     - Clicking the elephant icon:
       - ![SyncButton](./assets/android-sync-button.png)
     - Going to **File > Sync Project with gradle files**
   - NOTE: You will get a Java version error. This is expected.
8. Update the Java version
   - Go to **Android Studio > Settings > Build, Execution, Deployment > Build
     Tools > Gradle**
   - Under **Gradle Projects** There should be a project called **android**. In
     that project, find **Gradle JDK**.
   - Select **Java version 17**, which you had previously downloaded.
   - Click **Apply**
9. Add Configuration
   - Either go to **Run > Edit Configurations** or click **Add Configuration**
     in the center-right of the top bar
   - Click **Add new run configuration...**
   - Select **Android App** (should be in the **Other** section)
   - Name it whatever you would like
   - Next to **Module**, select **app**
   - Click **Ok**
10. Create a Virtual Device
    - Go to **View > Tool Windows > Device Manager** from the main menu bar, then click the **+**, and then click **Create Virtual Device**.
    - Select a phone you would like to use and press **Next**
    - Select the system image (you may need to download it). Click **Next**.
    - Click **Finish**
11. Update Gradle version
    - Go to **File > Project Structure...** from the main menu bar
    - Select **Project**
    - Update the Gradle Version to **8.9**
    - Click **Apply**
12. Sync the project again -- it should build without errors
    - NOTE: You may see a prompt to download the correct NDK version. Just click
      on the link provided to download it, and sync again
13. In the terminal, run `adb reverse tcp:8081 tcp:8081`
14. Click the play button to view the device. This should open the app virtual device
    within Android Studio.

## ⚙️ Troubleshoot

If you face problems with above commands regarding Android environment OR emulator/simulator, or Android build <br>
You can just run the metro server -> `yarn start` / `npm start` <br> (This will open separate terminal window and start the server. Keep it running.) and open respective IDEs Xcode or Android Studio -> Open the project -> and run the app.