Installation

Install react-native-sherpa-onnx in your React Native project and configure platform-specific setup.

Package Installation

npm install react-native-sherpa-onnx

Peer Dependencies

The library requires @dr.pogodin/react-native-fs for file operations:

npm install @dr.pogodin/react-native-fs

If your project uses Yarn v3+ or Plug’n’Play, configure Yarn to use the Node Modules linker to avoid postinstall issues.

Yarn PnP Configuration

If using Yarn v3+ with Plug’n’Play, add this to your .yarnrc.yml:

.yarnrc.yml

nodeLinker: node-modules

Alternatively, set the environment variable during install:

YARN_NODE_LINKER=node-modules yarn install

Platform Setup

iOS
Android

iOS Setup

The sherpa-onnx XCFramework is not shipped in the npm package (size ~80MB). It is downloaded automatically when you run pod install.

Install CocoaPods dependencies

Navigate to the ios directory and install pods:

cd ios
bundle install
bundle exec pod install

The podspec automatically runs scripts/setup-ios-framework.sh, which downloads the XCFramework from GitHub Releases. The version is pinned in third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG.

Verify framework download

The script downloads the XCFramework and libarchive sources. Libarchive is compiled from source as part of the Pod.You should see output similar to:

Downloading sherpa-onnx XCFramework v0.x.x...
✓ Framework downloaded successfully

Build your project

Return to the root directory and build:

cd ..
npx react-native run-ios

iOS Requirements

iOS 13.0+
Xcode 12.0+
CocoaPods 1.10+

Framework Architecture

The XCFramework includes:

libsherpa-onnx-cxx-api.a - C++ API merged into the static library
libarchive - Compiled from source for model archive extraction
Support for all iOS architectures (arm64, x86_64 for simulator)

The framework is fetched from GitHub Releases and automatically cached by CocoaPods.

Advanced: Building the Framework Locally

If you need a custom sherpa-onnx build (e.g., different version or patches):

Build the XCFramework using the build-sherpa-onnx-ios-framework workflow steps
Place it in ios/Frameworks/ before running pod install
The Pod will use the local framework instead of downloading

See third_party/sherpa-onnx-prebuilt for build details.

Android Setup

No additional setup required! The library automatically handles native dependencies via Gradle.

Sync Gradle

The native dependencies are automatically downloaded and linked:

cd android
./gradlew sync

Build your project

cd ..
npx react-native run-android

Android Requirements

Android API 24+ (Android 7.0+)
Gradle 7.0+
Android SDK 31+ (for compilation)

Native Libraries

The Gradle configuration automatically includes:

sherpa-onnx native libraries (CPU, NNAPI, XNNPACK, QNN support)
ONNX Runtime AAR for execution providers
JNI bindings for TurboModule communication

Execution Providers (Android)

Android supports multiple execution providers for hardware acceleration:

Provider	Description	Availability
CPU	Default CPU execution	All devices
NNAPI	Android Neural Networks API	Android 8.1+
XNNPACK	CPU-optimized inference	All devices
QNN	Qualcomm acceleration	Snapdragon devices

You can check provider support at runtime:

import { getAvailableProviders, getNnapiSupport, getXnnpackSupport, getQnnSupport } from 'react-native-sherpa-onnx';

const providers = await getAvailableProviders();
console.log('Available providers:', providers);

const nnapiSupport = await getNnapiSupport();
console.log('NNAPI available:', nnapiSupport.providerCompiled);

See Execution Providers for more details.

Play Asset Delivery (PAD)

Optionally use Play Asset Delivery for on-demand model downloads:

Configure fast-follow or on-demand asset packs in build.gradle
Use getAssetPackPath() to access downloaded models
See Model Setup for PAD configuration

Verify Installation

Test that the native library is loaded correctly:

App.tsx

import { testSherpaInit } from 'react-native-sherpa-onnx';

try {
  const result = await testSherpaInit();
  console.log('✓ sherpa-onnx initialized:', result);
} catch (error) {
  console.error('✗ Initialization failed:', error);
}

Expected output:

✓ sherpa-onnx initialized: sherpa-onnx native library loaded successfully

Requirements Summary

React Native

Version 0.70 or higher

Android

API 24+ (Android 7.0+)

iOS

iOS 13.0+, Xcode 12.0+

File System

@dr.pogodin/react-native-fs

Troubleshooting

iOS: Framework download fails

Symptom: Pod install fails with “Failed to download sherpa-onnx XCFramework”Solution:

Check your internet connection
Verify the release tag exists in GitHub Releases
Try manual download: bash scripts/setup-ios-framework.sh
Check third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG for the expected version

iOS: 'sherpa-onnx/c-api.h' file not found

Symptom: Build fails with missing header filesSolution:

Clean build folder: cd ios && rm -rf build && rm -rf ~/Library/Developer/Xcode/DerivedData
Re-install pods: bundle exec pod install --repo-update
Verify ios/Frameworks/sherpa-onnx.xcframework exists

Android: Build fails with 'Could not resolve com.sherpa-onnx:...'

Symptom: Gradle sync fails with dependency resolution errorsSolution:

Clear Gradle cache: cd android && ./gradlew clean
Sync project: ./gradlew --refresh-dependencies
Check android/build.gradle has mavenCentral() repository

Yarn PnP: Module not found errors

Symptom: Runtime errors with Yarn v3+ Plug’n’PlaySolution: Add to .yarnrc.yml:

nodeLinker: node-modules

Then run:

yarn install

testSherpaInit() fails

Symptom: testSherpaInit() throws an errorSolution:

iOS: Run cd ios && bundle exec pod install
Android: Run cd android && ./gradlew clean build
Rebuild the app completely
Check that peer dependencies are installed

If you encounter persistent issues, check the GitHub Issues or file a new issue with your error logs.

Next Steps

Quick Start

Build your first STT or TTS example

Model Setup

Learn how to bundle and load models

API Reference

Explore the complete API

Example App

Run the full-featured example app

Get Started

Core Features

Advanced

Configuration

Installation

Installation

Package Installation

Peer Dependencies

Yarn PnP Configuration

Platform Setup

iOS Setup

iOS Requirements

Framework Architecture

Advanced: Building the Framework Locally

Android Setup

Android Requirements

Native Libraries

Execution Providers (Android)

Play Asset Delivery (PAD)

Verify Installation

Requirements Summary

React Native

Android

iOS

File System

Troubleshooting

Next Steps

Quick Start

Model Setup

API Reference

Example App

Build docs developers (and LLMs) love

Get Started

Core Features

Advanced

Configuration

​Installation

​Package Installation

​Peer Dependencies

​Yarn PnP Configuration

​Platform Setup

​iOS Setup

​iOS Requirements

​Framework Architecture

​Advanced: Building the Framework Locally

​Android Setup

​Android Requirements

​Native Libraries

​Execution Providers (Android)

​Play Asset Delivery (PAD)

​Verify Installation

​Requirements Summary

React Native

Android

iOS

File System

​Troubleshooting

​Next Steps

Quick Start

Model Setup

API Reference

Example App

Build docs developers (and LLMs) love

Installation

Package Installation

Peer Dependencies

Yarn PnP Configuration

Platform Setup

iOS Setup

iOS Requirements

Framework Architecture

Advanced: Building the Framework Locally

Android Setup

Android Requirements

Native Libraries

Execution Providers (Android)

Play Asset Delivery (PAD)

Verify Installation

Requirements Summary

Troubleshooting

Next Steps