Xybrid
SDKs

React Native

On-device ML inference for React Native apps (iOS and Android)

The React Native package (@xybrid/react-native) wraps the same Rust core as the Swift and Kotlin SDKs in a TurboModule, so the API, models and error codes match every other binding. It is in preview: the surface is complete and tested, but may still change before 1.0.

Requirements

  • React Native 0.76+ with the New Architecture (Expo SDK 52+ with a development build — not Expo Go)
  • iOS 16.0+ (simulator builds need an Apple Silicon Mac)
  • Android 10 / API 29+ for releases 0.16.0 and later; API 24+ for releases before 0.16.0 (arm64-v8a, armeabi-v7a, x86_64). Phonon / Kitten TTS 2 speech runs on Android arm64-v8a only, not on iOS or the other ABIs

Installation

npm install @xybrid/react-native@0.20.0

For bare React Native, run cd ios && pod install. With Expo, run npx expo prebuild and use a development build; Expo Go cannot load the native module. The package itself needs no config plugin.

For releases 0.16.0 and later, your app's Android minSdkVersion must be 29 or higher; with a lower value the Gradle build fails at the manifest merge. The React Native and Expo templates currently default to 24, so raise it:

  • Expo: install expo-build-properties (npx expo install expo-build-properties), set android.minSdkVersion to 29, then run npx expo prebuild again. The plugin writes android.minSdkVersion=29 to android/gradle.properties; your own config plugin can set that property instead.

    app.json
    {
      "expo": {
        "plugins": [
          ["expo-build-properties", { "android": { "minSdkVersion": 29 } }]
        ]
      }
    }
  • Bare React Native: set minSdkVersion = 29 in the ext block of android/build.gradle.

On iOS, pod install downloads the Rust core from the matching GitHub Release and verifies its SHA-256. Offline or behind a proxy, set XYBRID_NATIVES_BASE_URL (a mirror) or XYBRID_XCFRAMEWORK_PATH (a local copy). On Android, Gradle resolves the Kotlin SDK from Maven Central.

On the iOS Simulator, llama.cpp runs on the CPU to avoid invalid special-token output. Physical iOS devices keep Metal acceleration. This change is included in 0.10.1.

Initialization

Local inference needs no setup. Pass an API key for cloud fallback and speculative cloud serving, then opt into Xybrid console trace export separately:

import { Xybrid, ObservabilityConfig } from '@xybrid/react-native';

await Xybrid.initialize({ apiKey: XYBRID_API_KEY });
await ObservabilityConfig.xybrid(XYBRID_API_KEY).setMetadataOnly(true).init();

Options apply once per app process; a later call with different options rejects with xybrid_config_error.

Observability can be replaced with another explicit configuration. An API key alone never enables export. The example records metadata only; enabled export captures governed text by default. ObservabilityConfig.otlp('http://collector:4318') configures traces, metrics and logs without a Xybrid key. Observation references use {trace_id, span_id}. Flush/shutdown delivery failures use xybrid_telemetry_delivery; retrying an inference does not recover its export.

Key prefixes and scopes, what gets exported, and provisional workspaces: see API keys.

Run a model

import { Envelope, GenerationConfigs, ModelLoader } from '@xybrid/react-native';

const model = await ModelLoader.fromRegistry('qwen3.5-0.8b').load();
const result = await model.run(Envelope.text('Name three rivers.'), {
  generationConfig: GenerationConfigs.greedy({ maxTokens: 64 }),
});
console.log(result.text, result.metrics.tokensPerSecond);
await model.release(); // weights live in native memory

Streaming and cancellation

runStreaming is an async generator. Pass an AbortSignal as the stop button; generation also stops when you break out of the loop:

const controller = new AbortController();
for await (const token of model.runStreaming(Envelope.text('Tell me a story'), {
  signal: controller.signal,
})) {
  append(token.token);
}
// controller.abort() → the run stops at the next token and rejects with xybrid_cancelled

Conversations

import { ConversationContext, Envelope } from '@xybrid/react-native';

const chat = await ConversationContext.create();
await chat.setSystem('You are concise.');
const question = Envelope.user('What is the capital of France?');
const reply = await model.run(question, { context: chat });
await chat.push(question);       // runs never modify the context:
await chat.push(reply.envelope); // push both turns after the run

More capabilities

The package covers the full SDK surface — see the package README for examples of each:

  • structured output (jsonSchemaToGbnf + generationConfig.grammar)
  • tool calling (generationConfig.tools, result.toolCalls, Envelope.toolResults)
  • vision (Envelope.image, Envelope.userMessage)
  • text-to-speech voices and speech recognition, batch and live (model.stream(); a session's flush() resolves a TranscriptionResult with text, durationMs, chunksProcessed and observation, where earlier releases resolved the transcript string)
  • Phonon (phonon-31m-en) and Kitten TTS 2 speech on Android arm64-v8a devices only; the engine's notices ship in the AAR under assets/xybrid/zzz/ and Android merges them into your APK
  • multi-stage pipelines (Pipeline.fromYaml / fromFile)
  • background downloads with progress, speculative cloud serving, model cache management and memory release

Errors

Every rejection carries a stable code, the same set on iOS and Android:

import { isRetryable, isXybridError } from '@xybrid/react-native';

try {
  await model.run(envelope);
} catch (error) {
  if (isXybridError(error) && error.code === 'xybrid_model_not_found') { /* … */ }
  if (isRetryable(error)) { /* retry later: network, rate limit, timeout, offline */ }
}

On this page