> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Build a React Native CLI app for iOS and Android and run it in the dev loop with hot reload.

For the local dev loop, generate a dev build using the Debug configuration. For automated testing or CI, use a release-like build once you're ready.

Prompt for your coding agent:

```text
Set up Revyl for this React Native app.

Read https://docs.revyl.com/frameworks/react-native.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

Use Debug builds, so the dev loop can hot reload from Metro. If the project builds both iOS and Android, start with iOS.

You're done when the app runs in the Revyl dev loop on a cloud simulator or emulator, and a JavaScript change hot reloads.

Ask me before anything that needs my login or approval.
```

## Build Guidance

To use the [Dev Loop](/dev-loop), a build is required **only on native code changes** (new native modules, Podfile/Gradle changes, build configuration). JS/TS changes hot reload via Metro — see [Dev Loop: Hot reload and rebuild configuration](/frameworks#hot-reload-and-rebuild-configuration) for the full breakdown.

## Build via Revyl CLI

### Prerequisites

- Node.js 18+
- Expo CLI (`npx expo`)
- EAS CLI (`npx eas-cli`) for local or cloud builds
- Revyl CLI installed and authenticated (`revyl auth login`)

### Setup

Initialize the project using the Revyl CLI:

```bash
revyl init
```

This detects React Native and writes named profiles with the applicable iOS and
Android recipes. Review or fill in the app IDs, commands, and output paths before
the first build. See [Types of Builds](/builds#types-of-builds) for more information.

Development builds power the dev loop. Preview builds are for testing and starting sessions when the Metro server isn't needed.

### Run Build

Run one profile/platform recipe in the cloud:

```bash
revyl build --profile development --platform ios
```

Profile names and their `ios` or `android` recipes live under
`build.profiles` in `.revyl/config.yaml`. There is no active/default profile.
See [Configuration](/remote-builds/configuration) for selection and recipe
fields.

This command automatically builds and uploads the app to Revyl, where you can use it to start sessions.


## Advanced Configuration

Revyl makes a best effort to determine the build commands to be used. If the build does not complete successfully modify the build commands manually in the [config.yaml file](/reference/cli/configuration).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bundle generation fails">
    ```bash
    # Reset cache
    npx react-native start --reset-cache

    # Clean install
    rm -rf node_modules && npm install
    ```
  </Accordion>

  <Accordion title="iOS build issues">
    Simulator builds don't require an Apple distribution certificate or
    provisioning profile. Let Xcode apply its default local signature so the
    app retains entitlements used by services such as Keychain. Don't set
    **Code Signing Identity** to "Don't Code Sign" or pass
    `CODE_SIGNING_ALLOWED=NO`.

    Missing dependencies:
    ```bash
    cd ios
    xcodebuild clean
    cd ..
    npx react-native run-ios
    ```
  </Accordion>

  <Accordion title="Android build issues">
    Gradle fails:
    ```bash
    cd android
    ./gradlew clean
    rm -rf ~/.gradle/caches
    ```

    Assets missing:
    ```bash
    # Verify bundle exists
    ls -la android/app/src/main/assets/
    # Should show index.android.bundle
    ```
  </Accordion>
</AccordionGroup>

## Dev loop

### React Native (bare)

Bare React Native projects use full hot reload via Metro, similar to Expo but without deep links. JS/TS changes appear on the device within seconds. Press `[r]` only when native dependencies change.

#### How detection works

The CLI looks for `react-native` in `package.json` dependencies **without** `expo` also being present. If both `react-native` and `expo` exist, the Expo provider takes precedence.

Detection confidence is **0.8** — higher than Swift (0.7) and Android (0.6), so bare RN projects are correctly identified even when `ios/` and `android/` directories are present.

Additional indicators that boost detection: `metro.config.js`, `metro.config.ts`, `react-native.config.js`, `react-native.config.ts`.

#### No app-native scheme needed

Unlike Expo, bare React Native hot reload does not use deep links. The dev
client loads the JavaScript bundle directly from the tunnel URL, so it needs no
custom app URL scheme or scheme-prefix configuration.

The `.revyl/config.yaml` uses `build.framework: react_native` and named
profiles containing the applicable iOS and Android recipes; it has no authored
hot-reload provider block.

#### iOS packager URL (HTTPS relay)

On iOS simulators, Revyl points the Debug app at the Metro relay by setting:

- `RCT_jsLocation` to the relay `host:443`
- `RCT_packager_scheme` to `https`

Those values are applied as launch arguments and seeded into the app's NSUserDefaults before launch. You should not patch `RCTBundleURLProvider.mm` (or change React Native's default `http` scheme) for the Revyl tunnel — without `https`, the app would request `http://…:443/…` against a TLS-only relay and fail to load the bundle.

#### Monorepo considerations

The same directory rules apply as Expo:

- Run all commands from the React Native app directory, not the monorepo root
- If `react-native` is hoisted, run `revyl init --detect` from the app directory;
  edit `build.framework` and the generated profile recipes, then run
  `revyl config validate`, if detection remains ambiguous
- Watch for multiple `.revyl/` directories in the monorepo