# React Native Dependencies
> Dependency & Compatibility guide for @revrag-ai/embed-react-native — recommended versions, supported React Native releases, verified stacks, and the pitfalls that break calls.
URL: /embed/integration/react-native-dependencies
Markdown: /embed/integration/react-native-dependencies.md
# Dependency & Compatibility Guide [#dependency--compatibility-guide]
For client apps integrating **`@revrag-ai/embed-react-native`** · SDK **1.1.0**
Everything a client app needs to install the SDK with the **right versions**, on a **supported React Native**, and avoid the handful of dependency pitfalls that otherwise show up as crashes or build failures. This is the short, practical version — the full per-version matrix ships inside the package (`node_modules/@revrag-ai/embed-react-native/COMPATIBILITY.md`).
***
## Table of contents [#table-of-contents]
1. [What to install](#1-what-to-install)
2. [Recommended versions](#2-recommended-versions) — plus two verified copy-paste stacks
3. [Supported React Native versions](#3-supported-react-native-versions)
4. [Required native setup](#4-required-native-setup-or-the-app-crashes)
5. [Must-know pitfalls](#5-must-know-pitfalls-the-ones-that-become-bug-reports)
6. [Package-manager notes](#6-package-manager-notes)
7. [Verify a healthy install](#7-verify-a-healthy-install)
***
## 1. What to install [#1-what-to-install]
The SDK relies on a set of **peer dependencies** — you install them in your app (the SDK does not bundle them). Copy-paste:
```bash
# The SDK
npm install @revrag-ai/embed-react-native
# Required peer dependencies
npm install \
@livekit/react-native \
@livekit/react-native-webrtc \
@react-native-async-storage/async-storage \
react-native-gesture-handler \
react-native-reanimated \
react-native-linear-gradient \
lottie-react-native \
react-native-safe-area-context
# iOS: native pods + register the SDK's bundled fonts (once)
cd ios && pod install && cd ..
npx react-native-asset
```
**Do NOT add `livekit-client` to your own `package.json`.** The SDK already includes it. Declaring your own copy causes **two copies** to be installed, which silently breaks the voice call (see [pitfall #1](#1-two-copies-of-livekit-client--the-1-cause-of-broken-calls)).
***
## 2. Recommended versions [#2-recommended-versions]
These are the **most-stable** versions to pair with the SDK. The SDK is developed and tested against **React Native 0.78 + React 19**; the New-Architecture stack on **RN 0.86** is also device-verified (see [section 3](#3-supported-react-native-versions)).
| Package | Recommended | Notes |
| ------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `react-native` | **0.78–0.81**, or **0.82–0.86** with the New-Arch stack | 0.78 is the reference; 0.86 is device-verified. |
| `react` | **19.0.0** | Use **18.3.1** on RN 0.76/0.77 (React 19 starts at RN 0.78). |
| `@livekit/react-native` | **2.11.1** (min **2.10.2**) | ≥ 2.10.2 carries the Hermes crash fix — required on Hermes/New Arch. |
| `@livekit/react-native-webrtc` | **144.1.1** (min **137.0.0**) | Must match your `@livekit/react-native` version. |
| `react-native-reanimated` | **3.19.5** | On RN ≥ 0.82 you must use **4.5.2** + `react-native-worklets` instead (see [pitfall #5](#5-wrong-reanimated--gesture-handler-for-your-rn-version)). |
| `react-native-gesture-handler` | **latest 2.x** (min **2.18.0**) | On RN ≥ 0.82 use **3.x**. |
| `react-native-safe-area-context` | **5.8.0** | One version covers the whole range. |
| `@react-native-async-storage/async-storage` | **2.2.0** | Avoid 3.x (breaking API). |
| `lottie-react-native` | **7.3.8** | — |
| `react-native-linear-gradient` | **2.8.3** | — |
### Verified known-good stacks (copy-paste) [#verified-known-good-stacks-copy-paste]
Two exact version sets confirmed by RevRag. Pick by your RN line.
**Stack A — RN 0.78–0.81 (reference line, classic UI stack):**
```jsonc
"react-native": "0.78.0", "react": "19.0.0",
"@livekit/react-native": "2.11.1", "@livekit/react-native-webrtc": "144.1.1",
"react-native-reanimated": "3.19.5",
"react-native-gesture-handler": "^2.22.0",
"react-native-safe-area-context": "5.8.0",
"@react-native-async-storage/async-storage": "2.2.0",
"lottie-react-native": "7.3.8", "react-native-linear-gradient": "2.8.3"
```
**Stack B — RN 0.82–0.86 (New-Architecture stack; the exact set device-verified on RN 0.86.3):**
```jsonc
"react-native": "0.86.3", "react": "19.2.3",
"@livekit/react-native": "2.11.1", "@livekit/react-native-webrtc": "144.1.1",
"react-native-reanimated": "4.5.2", "react-native-worklets": "0.11.0",
"react-native-gesture-handler": "3.0.2",
"react-native-safe-area-context": "5.8.0",
"@react-native-async-storage/async-storage": "2.2.0",
"lottie-react-native": "7.3.8", "react-native-linear-gradient": "2.8.3"
```
Stack B additionally needs `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) as the **last** Babel plugin.
***
## 3. Supported React Native versions [#3-supported-react-native-versions]
| RN | Status |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **0.78** | ✅ Tested reference — native Android build + on-device runtime (React 19, New Architecture, Hermes). |
| **0.76, 0.77, 0.79, 0.80, 0.81** | ✅ Supported — verified installs, same toolchain family. |
| **0.82 – 0.86** | ✅ **Verified on RN 0.86 (Android): native build + on-device runtime.** A fresh RN 0.86.3 app with the New-Architecture stack (Reanimated **4.5.2** + `react-native-worklets` **0.11.x** + Gesture Handler **3.0.2**) built cleanly (SDK Kotlin **and** C++ compiled) and ran on a physical device — the SDK's native module loaded and wrote its cache, LiveKit/WebRTC initialized, and `useInitialize` fetched the backend config. iOS build and a full end-to-end voice call on this range are not yet separately verified — pin the versions above and smoke-test. |
| **below 0.76** | ❌ Not supported. |
**On RN ≥ 0.82** you must use the New-Architecture stack (verified to install on 0.83/0.86): `react-native-reanimated@4.5.2`, `react-native-worklets@0.11.x`, `react-native-gesture-handler@3.0.2`, and switch the Babel plugin to `react-native-worklets/plugin` (kept last). React must satisfy your RN version's peer (e.g. RN 0.86 needs `react@^19.2.3`).
Always use **Hermes** (the tested engine). Minimum Android **`minSdkVersion` 24**, iOS **15.1** (iOS **16.0** on RN 0.81+).
***
## 4. Required native setup (or the app crashes) [#4-required-native-setup-or-the-app-crashes]
These are not optional — see the [React Native integration guide, section 1](/embed/integration/react-native#1-basic-integration) for the code.
1. **LiveKit native init** — `LiveKitReactNative.setup(...)` in Android `MainApplication` and iOS `AppDelegate`, **before** React Native starts. Missing it → `audioRecordSamplesDispatcher is not initialized!`.
2. **Do NOT call `registerGlobals()` yourself** — the SDK calls it inside `useInitialize`. A second call duplicates native event listeners. If your app already uses LiveKit, keep your existing native `setup()` (don't add another) and tell RevRag.
3. **Reanimated Babel plugin last** in `babel.config.js` (`react-native-reanimated/plugin`, or `react-native-worklets/plugin` on Reanimated 4). Animations break otherwise.
4. **iOS mic permission** — `NSMicrophoneUsageDescription` in `Info.plist` (crash without it).
5. **iOS fonts** — run `npx react-native-asset` once.
***
## 5. Must-know pitfalls (the ones that become bug reports) [#5-must-know-pitfalls-the-ones-that-become-bug-reports]
### 1. Two copies of `livekit-client` — the #1 cause of broken calls [#1-two-copies-of-livekit-client--the-1-cause-of-broken-calls]
**Why:** if your app declares its own `livekit-client`, the resolver installs a second copy nested under the SDK. WebRTC gets patched into one copy while the SDK's call object lives in the other, so the call silently fails.
**Fix:** do **not** put `livekit-client` in your `package.json`. Let the SDK provide it.
**Verify:** `npm ls livekit-client` must show **exactly one** copy.
### 2. An ERESOLVE / `react-dom` warning on install — safe to ignore [#2-an-eresolve--react-dom-warning-on-install--safe-to-ignore]
**Why:** LiveKit pulls in a web helper that transitively peers `react-dom`, which no React Native app ships. So `npm install` prints an `ERESOLVE overriding peer dependency` warning on every install, and `npm ls` may flag React as "invalid."
**Fix:** it's harmless — the SDK does not use `react-dom`. If your CI treats install warnings as errors or runs `npm ls` with a strict exit check, allow this one (or install with `--legacy-peer-deps`).
### 3. `react-native-gesture-handler` too old [#3-react-native-gesture-handler-too-old]
**Why:** the SDK's button is built on gesture-handler's 2.x `Gesture`/`GestureDetector` API; older 2.x builds red-box the app the moment the button renders.
**Fix:** use gesture-handler **≥ 2.18.0** (latest 2.x), or **3.x** on RN ≥ 0.82.
### 4. Android `minSdkVersion` below 24 [#4-android-minsdkversion-below-24]
**Why:** LiveKit's WebRTC hard-codes `minSdkVersion 24`.
**Symptom:** build fails — *"uses-sdk:minSdkVersion … cannot be smaller than version 24 declared in library \[livekit\_react-native-webrtc]"*.
**Fix:** set your app's `minSdkVersion` to **24** (or higher).
### 5. Wrong Reanimated / Gesture Handler for your RN version [#5-wrong-reanimated--gesture-handler-for-your-rn-version]
**Why:** Reanimated 4 and Gesture Handler 3 are **New-Architecture-only** (RN ≥ 0.82); Reanimated 3 and Gesture Handler 2 **cannot** run on RN ≥ 0.82.
**Fix:**
* RN ≤ 0.81: Reanimated **3.19.5** + Gesture Handler **2.x**.
* RN ≥ 0.82: Reanimated **4.5.2** + `react-native-worklets` + Gesture Handler **3.x**, and switch the Babel plugin to `react-native-worklets/plugin` (keep it last).
Never install `react-native-worklets` alongside Reanimated 3 — it breaks 3.x.
### 6. Keep the three LiveKit packages in lockstep [#6-keep-the-three-livekit-packages-in-lockstep]
**Why:** `@livekit/react-native`, `@livekit/react-native-webrtc`, and the bundled `livekit-client` are released as a matched set; mixing majors causes native/JS mismatch crashes.
**Fix:** upgrade them together — e.g. `@livekit/react-native` 2.11.1 with webrtc 144.1.1. On Hermes always use `@livekit/react-native` **≥ 2.10.2**.
***
## 6. Package-manager notes [#6-package-manager-notes]
| Manager | What to know |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **npm** (recommended) | Auto-installs peers and dedupes well. Expect the harmless `react-dom` ERESOLVE warning ([pitfall #2](#2-an-eresolve--react-dom-warning-on-install--safe-to-ignore)). |
| **yarn classic (1.x)** | Does **not** auto-install peers — you must install every peer from [section 1](#1-what-to-install) yourself, or the first import throws `MODULE_NOT_FOUND`. |
| **yarn berry (PnP)** | The default PnP linker breaks LiveKit resolution. Use `nodeLinker: node-modules` in `.yarnrc.yml`. |
| **pnpm** | `auto-install-peers` resolves `*` peers to **latest** (can pull Reanimated 4 / GH 3 onto an RN that can't use them). Pin the versions in [section 2](#2-recommended-versions) explicitly, and avoid `strict-peer-dependencies` (the `react-dom` peer makes it fail). |
***
## 7. Verify a healthy install [#7-verify-a-healthy-install]
```bash
npm ls livekit-client # must show exactly ONE copy (pitfall #1)
npm ls @livekit/react-native-webrtc # exactly one copy
```
Then build and place a test call **on a real device** (WebRTC audio is unreliable on emulators/simulators). If the button appears and a call connects, the dependency setup is good.
***
**More detail:** the full RN-version matrix ships inside the package as `COMPATIBILITY.md` (open `node_modules/@revrag-ai/embed-react-native` after install) · setup code → [React Native integration guide](/embed/integration/react-native).
Installation, native LiveKit setup, **`useInitialize`**, **`EmbedProvider`**, events, Action Intelligence, and troubleshooting.
***
## Support [#support]
* **Docs:** [https://docs.revrag.ai](https://docs.revrag.ai/)
* **Email:** [contact@revrag.ai](mailto:contact@revrag.ai)
* **Dashboard:** [app.revrag.ai](https://app.revrag.ai)