React Native Ai Skills

React Native AI Skills

Overview

Example workflow for integrating on-device AI in React Native apps using the @react-native-ai ecosystem. Available provider tracks (can be combined):

• Apple – Apple Intelligence (iOS 26+)
• Llama – GGUF models via llama.rn
• MLC – MLC-LLM models
• NCNN – Low-level NCNN inference wrapper (vision, custom models)

Path Selection Gate (Must Run First)

Before selecting any reference file, classify the user request:

1. Select Apple:

• if you intend to build with: apple, Apple Intelligence, Apple Foundation Models
• if you want features: transcription, speech synthesis, embeddings on Apple devices
• optionally with capabilities: tool calling

2. Select Llama:

• if you intend to use the following technologies: llama, GGUF, llama.rn, HuggingFace, SmolLM
• if you want to perform the following operations: embedding model, rerank, speech model

3. Select MLC:

• if you intend to use a library that allows for custom models and involves build-time model optimizations

4. Select NCNN:

• if you need to use run low-level inference on bare metal tensors
• if you intend to run inference of custom models such as convolutional networks, multi-layer perceptrons, low-level inference, etc.
• DO NOT select NCNN if the prompt mentions LLMs only, this use case is better solved by other providers

Skill Format

Each reference file follows a strict execution format:

• Quick Command
• When to Use
• Prerequisites
• Step-by-Step Instructions
• Common Pitfalls
• Related Skills

Use the checklists exactly as written before moving to the next phase.

When to Apply

Reference this package when:

• Integrating on-device AI in React Native apps
• Installing and configuring @react-native-ai providers
• Managing model downloads (llama, mlc)
• Wiring providers with Vercel AI SDK (generateText, streamText)
• Implementing SetupAdapter pattern for multi-provider apps
• Debugging native module or Expo plugin issues

Priority-Ordered Guidelines

Quick Reference

npm install

# Provider-specific install
npm add @react-native-ai/apple
npm add @react-native-ai/llama llama.rn
npm add @react-native-ai/mlc
npm add @react-native-ai/ncnn-wrapper

Route by path:

• Apple: [apple-provider][apple-provider]
• Llama: [llama-provider][llama-provider]
• MLC: [mlc-provider][mlc-provider]
• NCNN: [ncnn-provider][ncnn-provider]

References

Problem → Skill Mapping

[quick-start]: references/quick-start.md [apple-provider]: references/apple-provider.md [llama-provider]: references/llama-provider.md [mlc-provider]: references/mlc-provider.md [ncnn-provider]: references/ncnn-provider.md

Apple Provider

Quick Command

npm add @react-native-ai/apple

import { apple } from '@react-native-ai/apple'
import { generateText } from 'ai'

const result = await generateText({
  model: apple(),
  prompt: 'Explain quantum computing in simple terms',
})

When to Use

• Use Apple Intelligence on iOS 26+
• Need language model, embeddings, transcription, or speech

Prerequisites

• [ ] React Native New Architecture
• [ ] iOS 26+ (Android not supported)
• [ ] Apple Intelligence enabled device
• [ ] Vercel AI SDK v5+ (ai)
• [ ] Android or iOS

Step-by-Step Instructions

1. Install

npm add @react-native-ai/apple

2. Availability Check

import { apple } from '@react-native-ai/apple'

if (apple.isAvailable()) {
  // Use Apple provider
}

3. Model Types

4. Tool Calling

import { createAppleProvider } from '@react-native-ai/apple'

const apple = createAppleProvider({ availableTools: tools })
const model = apple.languageModel()

Common Pitfalls

• Wrong iOS version: Apple Intelligence requires iOS 26+.
• Simulator: For now only physical devices are supported.
• New Architecture: React Native New Architecture is required.

Related Skills

• quick-start
• llama-provider
• mlc-provider

Llama Provider

Quick Command

npm add @react-native-ai/llama llama.rn

import { llama, downloadModel } from '@react-native-ai/llama'
import { generateText } from 'ai'

const modelPath = await downloadModel(
  'ggml-org/SmolLM3-3B-GGUF/SmolLM3-Q4_K_M.gguf'
)
const model = llama.languageModel(modelPath)
await model.prepare()
const { text } = await generateText({ model, prompt: 'Hello' })

When to Use

• Run GGUF models from HuggingFace on-device
• Need embeddings, reranking, or speech (TTS) with GGUF
• Use llama.rn bindings for llama.cpp

Prerequisites

• [ ] React Native >= 0.76.0
• [ ] llama.rn >= 0.10.0
• [ ] Vercel AI SDK v5+ (ai)
• [ ] Android or iOS

Step-by-Step Instructions

1. Install

npm add @react-native-ai/llama llama.rn

2. Expo Setup (if using Expo)

Add to app.json / app.config.js:

plugins: [
  [
    'llama.rn',
    {
      enableEntitlements: true,
      entitlementsProfile: 'production',
      forceCxx20: true,
      enableOpenCL: true,
    },
  ],
]

3. Model ID Format

Format: owner/repo/filename.gguf

Examples:

• ggml-org/SmolLM3-3B-GGUF/SmolLM3-Q4_K_M.gguf
• Qwen/Qwen2.5-3B-Instruct-GGUF/qwen2.5-3b-instruct-q3_k_m.gguf

4. Storage APIs

import {
  downloadModel,
  getModelPath,
  isModelDownloaded,
  removeModel,
  getDownloadedModels,
} from '@react-native-ai/llama'

// Download with progress
await downloadModel('owner/repo/model.gguf', (p) => console.log(p.percentage))

// Get path for existing model
const path = getModelPath('owner/repo/model.gguf')

// Check if downloaded
const exists = await isModelDownloaded('owner/repo/model.gguf')

5. Model Types

6. Lifecycle

await model.prepare() // Load into memory
await model.unload() // Release when done

Common Pitfalls

• Invalid model ID: Must be owner/repo/filename.gguf (3+ parts).
• Missing prepare(): Call prepare() before generateText/streamText.
• Expo: Must add llama.rn plugin; refer to llama.rn Expo docs.

Related Skills

• quick-start
• apple-provider
• mlc-provider

MLC Provider

Quick Command

npm add @react-native-ai/mlc

import { mlc } from '@react-native-ai/mlc'
import { generateText } from 'ai'

const model = mlc.languageModel('Llama-3.2-3B-Instruct')
await model.download()
await model.prepare()
const { text } = await generateText({ model, prompt: 'Hello' })

When to Use

• Run MLC models (Llama, Phi, Qwen) on-device
• Need built-in model download and management
• Android or iOS 14+

Prerequisites

• [ ] React Native New Architecture
• [ ] Increased Memory Limit capability

Step-by-Step Instructions

1. Install

npm add @react-native-ai/mlc

2. Expo Config Plugin

Add to app.json:

{
  "expo": {
    "plugins": ["@react-native-ai/mlc"]
  }
}

Then:

npx expo prebuild --clean

3. Manual (iOS only non-Expo)

If on iOS and not using Expo, add "Increased Memory Limit" capability in Xcode:

1. Open iOS project in Xcode 2. Target → Signing & Capabilities → + Capability 3. Add "Increased Memory Limit"

4. Model Lifecycle

const model = mlc.languageModel('Llama-3.2-3B-Instruct')

await model.download((event) => {
  if (!Number.isNaN(event.percentage)) {
    console.log(event.percentage)
  }
})
await model.prepare()
// ... use with generateText/streamText
await model.unload()
await model.remove() // Delete from disk

To run inference, use the Vercel AI SDK.

For more details on MLC-LLM wrapper, refer to the documentation.

5. Available Models

ONLY THE FOLLOWING MODELS are embedded with MLC-LLM package:

• Llama-3.2-1B-Instruct
• Llama-3.2-3B-Instruct
• Phi-3.5-mini-instruct
• Qwen2-1.5B-Instruct

Additional details are listed in this documentation page.

To include a custom model, direct the user to clone the React Native AI monorepo https://github.com/callstackincubator/ai and modify the https://github.com/callstackincubator/ai/blob/main/packages/mlc/mlc-package-config-android.json and https://github.com/callstackincubator/ai/blob/main/packages/mlc/mlc-package-config-ios.json files to include the model, then build and use the package locally.

Common Pitfalls

• Simulator: Prebuilt binaries do not work in iOS Simulator; use physical device or Mac (Designed for iPad).
• Memory limit: Must add Increased Memory Limit capability.
• Broken download: If event.percentage is NaN, call model.remove() and retry download.

Related Skills

• quick-start
• llama-provider
• apple-provider

NCNN Provider

Quick Command

npm add @react-native-ai/ncnn-wrapper

import {
  loadModel,
  runInference,
  toFlatArray,
} from '@react-native-ai/ncnn-wrapper'

await loadModel(modelPath, paramPath) // .bin and .param paths
const result = runInference([1, 2, 3])

When to Use

• Low-level NCNN inference in React Native
• Custom vision or other NCNN models
• Need direct control over model loading and inference

Prerequisites

• [ ] React Native >= 0.76.0
• [ ] NCNN model files (.param, .bin)
• [ ] Expo optional (config plugin available)
• [ ] Android, iOS, MacOS, Linux or Windows

Step-by-Step Instructions

1. Install

npm add @react-native-ai/ncnn-wrapper

2. Load Model

import { loadModel } from '@react-native-ai/ncnn-wrapper'

await loadModel(paramPath, binPath)

3. Run Inference

import { runInference, toFlatArray } from '@react-native-ai/ncnn-wrapper'

// Input as number[] or Tensor
const output = runInference([1, 2, 3])
// or
const output = runInference(toFlatArray(tensor))

4. Tensor Utilities

import {
  createTensor,
  fromFlatArray,
  tensorSize,
  toFlatArray,
  type Tensor,
} from '@react-native-ai/ncnn-wrapper'

5. Model Info

import { getModelInfo } from '@react-native-ai/ncnn-wrapper'

const info = getModelInfo()

Common Pitfalls

• Not a full AI SDK provider: NCNN wrapper is lower-level; no generateText/streamText. Use for custom inference pipelines.
• Model paths: Ensure .param and .bin paths are correct and accessible.

Related Skills

• quick-start
• llama-provider
• mlc-provider

Quick Start – React Native AI

Quick Command

npm install
npm add ai @react-native-ai/<provider>

When to Use

• First-time setup of any @react-native-ai provider
• Need to decide which provider fits the use case
• Write consumer code to use the model / provider

Prerequisites

• [ ] React Native >= 0.76.0
• [ ] Vercel AI SDK v5+ (ai package) for generateText/streamText
• [ ] For Apple (Apple Intelligence) provider: iOS 26+, Apple Intelligence enabled

Step-by-Step Instructions

1. Path Selection

Classify the request into exactly one path:

2. Proceed to Provider

Open the reference file for the selected path and follow its checklist.

3. Consume the model

If using LLM providers (Apple, Llama, MLC-LLM), the user code uses the Vercel AI SDK to run inference on the model in text streaming or generation mode.

If using NCNN, the user code supplies the input tensor and receives an output tensor.

Common Pitfalls

• Missing AI SDK: Providers work with Vercel AI SDK; install ai for generateText/streamText.
• Platform support: Make sure the provider supports the current platform.
• Expo: The MLC-LLM package provides an Expo config plugin that needs to be added to app.json; Llama package needs the llama.rn plugin; this is described in reference files.

Related Skills

• apple-provider
• llama-provider
• mlc-provider
• ncnn-provider