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

# Installation

> Add the RunAnywhere React Native SDK to your project

## Package Installation

Choose the packages based on your feature requirements:

### Full Installation (All Features)

```bash theme={null}
npm install @runanywhere/core @runanywhere/llamacpp @runanywhere/onnx
# or
yarn add @runanywhere/core @runanywhere/llamacpp @runanywhere/onnx
```

### LLM Only (Text Generation)

```bash theme={null}
npm install @runanywhere/core @runanywhere/llamacpp
# or
yarn add @runanywhere/core @runanywhere/llamacpp
```

### Voice Only (STT/TTS)

```bash theme={null}
npm install @runanywhere/core @runanywhere/onnx
# or
yarn add @runanywhere/core @runanywhere/onnx
```

### Required Peer Dependencies

The SDK uses Nitro Modules for its native bridge and requires file system access for model downloads:

```bash theme={null}
# Required: Native bridge layer
npm install react-native-nitro-modules

# Required: File system access for model downloads
npm install react-native-fs@^2.20.0
```

<Warning>
  `react-native-fs` is **required** for model downloads. `react-native-nitro-modules` is required
  for the native bridge between JavaScript and the SDK's native inference engines.
</Warning>

<Info>
  Include only the SDK modules you need. Each native module adds to your app size: -
  **@runanywhere/core**: \~2MB (required) - **@runanywhere/llamacpp**: \~15-25MB (for LLM text
  generation) - **@runanywhere/onnx**: \~50-70MB (for STT, TTS, and VAD)
</Info>

## Package Overview

| Package                 | Size      | Features                           |
| ----------------------- | --------- | ---------------------------------- |
| `@runanywhere/core`     | \~2MB     | Core SDK, model management, events |
| `@runanywhere/llamacpp` | \~15-25MB | LLM text generation (GGUF models)  |
| `@runanywhere/onnx`     | \~50-70MB | STT, TTS, VAD (ONNX models)        |

## Supported Model Formats

| Format | Extension | Backend      | Use Case            |
| ------ | --------- | ------------ | ------------------- |
| GGUF   | `.gguf`   | LlamaCPP     | LLM text generation |
| ONNX   | `.onnx`   | ONNX Runtime | STT, TTS, VAD       |

## iOS Setup

<Warning>
  `automaticPodsInstallation` must be set to `false` in `react-native.config.js` because
  `@runanywhere` packages use `podspecPath` which is not compatible with RN 0.83+ CLI auto-install.
  Pods must be installed manually.
</Warning>

```bash theme={null}
cd ios && pod install && cd ..
```

### Podfile Requirements

The `NitroModules` pod must be manually added in your Podfile:

```ruby Podfile theme={null}
pod 'NitroModules', :path => '../node_modules/react-native-nitro-modules'
```

### New Architecture (iOS)

If you encounter crashes with `react-native-screens` or native stack navigator on iOS with New Architecture, disable it:

```ruby Podfile theme={null}
:fabric_enabled => false,
:new_arch_enabled => false,
```

Use `@react-navigation/stack` (JS-based) instead of `@react-navigation/native-stack` on iOS, and mock `react-native-screens` via Metro config if needed.

### iOS Permissions

Add required permissions to your `Info.plist`:

```xml Info.plist theme={null}
<!-- Required for STT/VAD with microphone -->
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for speech recognition and voice agent features.</string>

<!-- Required for on-device speech recognition -->
<key>NSSpeechRecognitionUsageDescription</key>
<string>This app uses on-device speech recognition to transcribe your voice.</string>
```

<Note>
  `NSMicrophoneUsageDescription` is only required if you're using STT or VAD with microphone input.
  The app does NOT need `NSAllowsArbitraryLoads` — configure specific exceptions as needed.
</Note>

## Android Setup

Native libraries are automatically downloaded during the Gradle build.

### Android Build Requirements

| Requirement | Minimum Version   |
| ----------- | ----------------- |
| Android SDK | compileSdk 36     |
| Android NDK | 28.0.13004108     |
| JDK         | 17+               |
| Min API     | 24 (Android 7.0+) |
| Kotlin      | 2.1.20            |

### Gradle Configuration

In `android/settings.gradle`, explicitly include `react-native-nitro-modules`:

```gradle settings.gradle theme={null}
include ':react-native-nitro-modules'
project(':react-native-nitro-modules').projectDir =
    new File(rootProject.projectDir, '../node_modules/react-native-nitro-modules/android')
```

In `android/app/build.gradle`, add `pickFirsts` to resolve duplicate native library conflicts:

```gradle app/build.gradle theme={null}
android {
    packagingOptions {
        pickFirsts += ['**/libc++_shared.so', '**/libjsi.so', '**/libfbjni.so',
                       '**/libfolly_runtime.so', '**/libreactnative.so']
    }
}
```

### Android Permissions

Add required permissions to your `AndroidManifest.xml`:

```xml AndroidManifest.xml theme={null}
<!-- Required for model downloads -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required for STT/VAD with microphone -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

<Note>
  Runtime permission for `RECORD_AUDIO` must be requested via `PermissionsAndroid.request()` before
  using STT or Voice Pipeline features.
</Note>

### Running on Physical Device

1. **Enable Developer Options:** Settings → About Phone → Tap "Build Number" 7 times
2. **Enable USB Debugging:** Settings → Developer Options → USB Debugging
3. **Connect device:** `adb devices` (should show your device)
4. **Port forwarding:** `adb reverse tcp:8081 tcp:8081`
5. **Start Metro:** `npm start`
6. **Run app:** `npx react-native run-android`

### ProGuard Rules

If using ProGuard/R8 minification, add these rules to `proguard-rules.pro`:

```proguard proguard-rules.pro theme={null}
-keep class com.runanywhere.** { *; }
-keepclassmembers class com.runanywhere.** { *; }
-keep class ai.runanywhere.** { *; }
```

## Troubleshooting Installation

### iOS: Pod Install Fails

```bash theme={null}
# Clean and reinstall pods
cd ios
rm -rf Pods Podfile.lock
pod cache clean --all
pod install
cd ..
```

### Android: Native Library Not Found

This error typically occurs when running on an emulator:

```
dlopen failed: library "librunanywherecore.so" not found
```

**Solution:** Use a physical ARM64 Android device. Emulators are not supported.

If using a physical device:

```bash theme={null}
# Clean and rebuild
cd android
./gradlew clean
cd ..
npx react-native run-android
```

### Android: "hermesEnabled" Property Not Found

**Solution:** Copy the gradle.properties example file:

```bash theme={null}
cp android/gradle.properties.example android/gradle.properties
```

### Android: "Unable to load script" on Device

**Solution:** Set up port forwarding for Metro bundler:

```bash theme={null}
adb reverse tcp:8081 tcp:8081
```

### Android: Grey Screen After Launch

**Solution:** Metro bundler may have stopped. Restart it:

```bash theme={null}
npm start
```

### Metro: Module Resolution Issues

```bash theme={null}
# Reset Metro bundler cache
npx react-native start --reset-cache
```

### Both Platforms: Fresh Build

```bash theme={null}
# Complete clean build
rm -rf node_modules
npm install
cd ios && pod install && cd ..
npx react-native run-ios  # or run-android
```

## Native Binary Sizes

| Framework         | iOS (xcframework) | Android (so) |
| ----------------- | ----------------- | ------------ |
| RACommons         | \~2MB             | \~2MB        |
| RABackendLLAMACPP | \~15-25MB         | \~15-25MB    |
| RABackendONNX     | \~50-70MB         | \~50-70MB    |

<Warning>
  The ONNX backend is significantly larger due to the ONNX Runtime library. If you only need LLM
  text generation, consider installing just `@runanywhere/llamacpp` to reduce app size.
</Warning>

## Next Steps

<Card title="Quick Start" icon="rocket" href="/react-native/quick-start">
  Initialize the SDK and run your first inference →
</Card>