RevRag.ai
In-App Agent
DocumentationIn-App AgentAPI ReferenceTrust & Security
View as Markdownllms.txt

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

  1. What to install
  2. Recommended versions — plus two verified copy-paste stacks
  3. Supported React Native versions
  4. Required native setup
  5. Must-know pitfalls
  6. Package-manager notes
  7. Verify a healthy 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:

# 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).

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).

PackageRecommendedNotes
react-native0.78–0.81, or 0.82–0.86 with the New-Arch stack0.78 is the reference; 0.86 is device-verified.
react19.0.0Use 18.3.1 on RN 0.76/0.77 (React 19 starts at RN 0.78).
@livekit/react-native2.11.1 (min 2.10.2)≥ 2.10.2 carries the Hermes crash fix — required on Hermes/New Arch.
@livekit/react-native-webrtc144.1.1 (min 137.0.0)Must match your @livekit/react-native version.
react-native-reanimated3.19.5On RN ≥ 0.82 you must use 4.5.2 + react-native-worklets instead (see pitfall #5).
react-native-gesture-handlerlatest 2.x (min 2.18.0)On RN ≥ 0.82 use 3.x.
react-native-safe-area-context5.8.0One version covers the whole range.
@react-native-async-storage/async-storage2.2.0Avoid 3.x (breaking API).
lottie-react-native7.3.8—
react-native-linear-gradient2.8.3—

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):

"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):

"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

RNStatus
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)

These are not optional — see the React Native integration guide, section 1 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)

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

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

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

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

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

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

ManagerWhat to know
npm (recommended)Auto-installs peers and dedupes well. Expect the harmless react-dom ERESOLVE warning (pitfall #2).
yarn classic (1.x)Does not auto-install peers — you must install every peer from section 1 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.
pnpmauto-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 explicitly, and avoid strict-peer-dependencies (the react-dom peer makes it fail).

7. Verify a healthy install

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.

Back to React Native integration

Installation, native LiveKit setup, useInitialize, EmbedProvider, events, Action Intelligence, and troubleshooting.

Support