Expo Integration Guide

The complete integration path for adding on-device LLM, STT, and TTS to a React Native app with the RunAnywhere SDK, written against SDK 0.20.27. It is written step by step, so a coding agent can follow it as-is. Every step assumes the app runs in RunAnywhere AI Studio rather than standard Expo Go.

Working starter project

The RunAnywhere Expo Demo is a working Expo template with a prebuilt Android APK.

RunAnywhere AI Studio app

You must run the app inside RunAnywhere AI Studio, a fork of Expo Go carrying the native libraries the SDK needs. Standard Expo Go does not include them, so RunAnywhere.initialize() and every inference call below fail there with a missing native module.

Your JS bundle connects to Metro as usual and runs inside AI Studio, which supplies the native layer: LlamaCPP for LLM, ONNX Runtime for STT and TTS, and the native audio module.

1. Install

npm install @runanywhere/core @runanywhere/llamacpp @runanywhere/onnx

package.json

{
  "dependencies": {
    "@runanywhere/core": "^0.20.27",
    "@runanywhere/llamacpp": "^0.20.27",
    "@runanywhere/onnx": "^0.20.27"
  }
}

Add @runanywhere/mlx (^0.20.27) for Apple MLX on physical iOS devices, and @runanywhere/qhexrt (^0.20.19, note the different version) for the Qualcomm Hexagon NPU.

2. Register a backend, then initialize

App.tsx

import { RunAnywhere } from '@runanywhere/core'
import { LlamaCPP } from '@runanywhere/llamacpp'
import { ONNX } from '@runanywhere/onnx'
import { useEffect, useState } from 'react'

export default function App(): React.JSX.Element {
  const [ready, setReady] = useState(false)

  useEffect(() => {
    ;(async () => {
      await LlamaCPP.register()
      await ONNX.register()
      await RunAnywhere.initialize({})
      setReady(true)
    })()
  }, [])

  if (!ready) return <Loading />
  return <RootNavigator />
}

Register backends before initialize(). The plugin registry has to know which engines exist before the first model load.

3. Register models

import { RunAnywhere, ModelCategory, InferenceFramework } from '@runanywhere/core'

await RunAnywhere.models.register({
  id: 'qwen3-0.6b',
  name: 'Qwen3 0.6B',
  url: 'https://example.com/qwen3-0.6b-q4_k_m.gguf',
  framework: InferenceFramework.INFERENCE_FRAMEWORK_LLAMA_CPP,
  category: ModelCategory.MODEL_CATEGORY_LANGUAGE,
})

API reference

Model management

const models = await RunAnywhere.models.list()
const resident = await RunAnywhere.models.loaded(ModelCategory.MODEL_CATEGORY_LANGUAGE)

for await (const event of RunAnywhere.models.download('qwen3-0.6b')) {
  if (event.type === 'progress') setProgress(event.fraction ?? 0)
}

await RunAnywhere.models.load('qwen3-0.6b')
await RunAnywhere.models.unload('qwen3-0.6b')
await RunAnywhere.models.delete('qwen3-0.6b')

There is no models.get(id) on React Native. Use models.loaded(category), or list() and filter.

LLM

// One-shot
const result = await RunAnywhere.llm.generate('Explain on-device AI', {
  model: 'qwen3-0.6b',
  maxOutputTokens: 200,
  temperature: 0.8,
})

// Streaming
for await (const event of RunAnywhere.llm.generateStream(prompt)) {
  if (event.type === 'textDelta') setText((t) => t + event.text)
}

Break out of the loop to cancel. A conversation is the same method with an array:

const reply = await RunAnywhere.llm.generate([
  { role: 'system', content: 'You are a concise assistant.' },
  { role: 'user', content: 'Why does on-device matter?' },
])

Speech to text

import { AudioInputs } from '@runanywhere/core'

const transcription = await RunAnywhere.stt.transcribe(AudioInputs.pcm16(pcmBytes), {
  language: 'en',
  punctuation: true,
})

console.log(transcription.text)

Streaming, when you have an async iterable of audio:

for await (const event of RunAnywhere.stt.transcribeStream(microphone())) {
  if (event.type === 'partial') setPreview(event.text)
}

There is no stt.openStream on React Native.

Text to speech

const audio = await RunAnywhere.tts.synthesize(text, {
  voice: 'en_US-amy-medium',
  speed: 1.0,
})

// Or play it directly. speak() is synchronous here.
const handle = RunAnywhere.tts.speak(text)
await RunAnywhere.tts.stop()

Voice agent

const session = await RunAnywhere.voice.createSession({
  stt: { id: 'whisper-base' },
  llm: { id: 'qwen3-0.6b' },
  tts: { id: 'piper-en-amy' },
  generation: {
    systemPrompt: 'Answer in one or two sentences.',
    maxOutputTokens: 100,
  },
})

await session.start()
await session.say('Hello. What can I help with?')

// always
await session.close()

The ModelService pattern

A React context that owns registration and readiness, so screens do not each re-initialize.

ModelService.tsx

import { RunAnywhere, ModelCategory } from '@runanywhere/core'
import { LlamaCPP } from '@runanywhere/llamacpp'
import { ONNX } from '@runanywhere/onnx'
import { createContext, useContext, useEffect, useMemo, useState } from 'react'
import type { ModelInfo } from '@runanywhere/core'

interface ModelContextValue {
  ready: boolean
  models: ModelInfo[]
  download: (id: string) => AsyncIterable<unknown>
  load: (id: string) => Promise<void>
}

const ModelContext = createContext<ModelContextValue | null>(null)

export function ModelProvider({ children }: { children: React.ReactNode }): React.JSX.Element {
  const [ready, setReady] = useState(false)
  const [models, setModels] = useState<ModelInfo[]>([])

  useEffect(() => {
    ;(async () => {
      await LlamaCPP.register()
      await ONNX.register()
      await RunAnywhere.initialize({})
      setModels(await RunAnywhere.models.list())
      setReady(true)
    })()
  }, [])

  const value = useMemo<ModelContextValue>(
    () => ({
      ready,
      models,
      download: (id) => RunAnywhere.models.download(id),
      load: async (id) => {
        await RunAnywhere.models.load(id)
      },
    }),
    [ready, models]
  )

  return <ModelContext.Provider value={value}>{children}</ModelContext.Provider>
}

export function useModels(): ModelContextValue {
  const value = useContext(ModelContext)
  if (!value) throw new Error('useModels must be used inside ModelProvider')
  return value
}

Chat screen

ChatScreen.tsx

import { RunAnywhere, SDKException } from '@runanywhere/core'
import { useCallback, useEffect, useRef, useState } from 'react'
import { Button, ScrollView, Text, TextInput, View } from 'react-native'

export function ChatScreen(): React.JSX.Element {
  const [prompt, setPrompt] = useState('')
  const [reply, setReply] = useState('')
  const [busy, setBusy] = useState(false)

  const cancelled = useRef(false)
  const buffer = useRef('')

  useEffect(
    () => () => {
      cancelled.current = true
    },
    []
  )

  useEffect(() => {
    const id = setInterval(() => {
      if (buffer.current) {
        setReply((t) => t + buffer.current)
        buffer.current = ''
      }
    }, 50)
    return () => clearInterval(id)
  }, [])

  const send = useCallback(async () => {
    setBusy(true)
    setReply('')
    try {
      for await (const event of RunAnywhere.llm.generateStream(prompt)) {
        if (cancelled.current) break
        if (event.type === 'textDelta') buffer.current += event.text
      }
    } catch (error) {
      setReply(error instanceof SDKException ? error.message : String(error))
    } finally {
      setBusy(false)
    }
  }, [prompt])

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <ScrollView style={{ flex: 1 }}>
        <Text>{reply}</Text>
      </ScrollView>
      <TextInput value={prompt} onChangeText={setPrompt} placeholder="Ask something" />
      <Button title="Send" onPress={send} disabled={busy || !prompt} />
    </View>
  )
}

Two things here matter and are easy to skip: the cancelled ref stops the loop writing state after unmount, and buffering tokens on a 50ms interval stops a re-render per token.

Errors

import { SDKException } from '@runanywhere/core'

try {
  const result = await RunAnywhere.llm.generate(prompt)
} catch (error) {
  if (error instanceof SDKException) {
    console.log(error.code, error.message)
  } else {
    throw error
  }
}

On React Native, an in-flight streaming failure is thrown into the consumer, so a try around the for await catches it. That differs from the Web SDK, where the failure arrives as a failed event.

Package compatibility

react-native-reanimated

Works. Keep it on the version Expo’s SDK pins rather than the latest, since a mismatch surfaces as a native crash that looks like an SDK problem.

Other native libraries

Anything that ships its own native code has to be present in the AI Studio build. If you add a native dependency the fork does not carry, the JS side loads and the native module is missing at runtime.

Troubleshooting

Symptom	Cause
”No provider could handle the request”	A backend was not registered before `initialize()`
Native module missing	Running in standard Expo Go rather than RunAnywhere AI Studio
Nothing infers on an emulator	The Android emulator has no arm64 native libraries
`MLX.register()` returns false	MLX needs physical iOS hardware
Microphone fails	Runtime permission not granted
App reloads mid-download	Metro fast refresh. Downloads resume; loads do not.

Get started

Going further

Working starter project

RunAnywhere AI Studio app

1. Install

2. Register a backend, then initialize

3. Register models

API reference

Model management

LLM

Speech to text

Text to speech

Voice agent

The ModelService pattern

Chat screen

Errors

Package compatibility

react-native-reanimated

Other native libraries

Troubleshooting

​Working starter project

​RunAnywhere AI Studio app

​1. Install

​2. Register a backend, then initialize

​3. Register models

​API reference

​Model management

​LLM

​Speech to text

​Text to speech

​Voice agent

​The ModelService pattern

​Chat screen

​Errors

​Package compatibility

​react-native-reanimated

​Other native libraries

​Troubleshooting

Working starter project

RunAnywhere AI Studio app

1. Install

2. Register a backend, then initialize

3. Register models

API reference

Model management

LLM

Speech to text

Text to speech

Voice agent

The ModelService pattern

Chat screen

Errors

Package compatibility

react-native-reanimated

Other native libraries

Troubleshooting