React Native Foundation Models

React Native bindings for Apple’s on-device FoundationModels framework. Run LLMs directly on Apple Silicon devices with no API costs and full offline support.

Experimental: This library is under active development. The API may change.

Requirements

• iOS 26.0+
• Apple Silicon (iPhone 15 Pro or later, M-series Macs)
• Apple Intelligence enabled on device

Features

• ✅ Stateful sessions (multi-turn conversations)
• ✅ Tool calling with Expo config plugin
• ✅ Streaming responses
• ☑️ Guided generation (response schemas)

Installation

npx expo install @drewalth/react-native-foundation-models

Basic Usage

import {
  FoundationModelSession,
  isAvailable,
} from "@drewalth/react-native-foundation-models";

if (isAvailable()) {
  const session = new FoundationModelSession({
    instructions: "You are a concise science educator.",
  });

  // Send a message
  const response = await session.sendMessage(
    "Explain quantum computing in one sentence.",
  );

  // Multi-turn conversation - history is maintained automatically
  const followUp = await session.sendMessage("Can you give me an example?");

  // Clean up when done
  session.destroy();
}

Tool Calling

Tools are defined at build time via the Expo config plugin and implemented at runtime via JavaScript handlers. This allows the on-device model to invoke your app’s functionality.

1. Define Tools in Expo Config

// app.config.js
export default {
  expo: {
    plugins: [
      [
        "@drewalth/react-native-foundation-models",
        {
          tools: [
            {
              name: "getCurrentTime",
              description: "Get the current date and time",
              parameters: {
                type: "object",
                properties: {
                  timezone: {
                    type: "string",
                    description: "IANA timezone (e.g., 'America/New_York')",
                  },
                },
                required: [],
              },
            },
          ],
        },
      ],
    ],
  },
};

2. Implement Handlers at Runtime

const session = new FoundationModelSession({
  instructions: "You are a helpful assistant.",
  tools: {
    getCurrentTime: ({ timezone }) => {
      return new Date().toLocaleString("en-US", {
        timeZone: timezone || undefined,
      });
    },
  },
});

// The model will automatically use tools when appropriate
const response = await session.sendMessage("What time is it in Tokyo?");

3. Run Prebuild

After configuring tools, regenerate native code:

npx expo prebuild