react-native-local-ai

Offline ChatGPT-style SDK for React Native.

npm install react-native-local-ai

import { AIChat } from 'react-native-local-ai';

export default function App() {
  return <AIChat />;
}

What This Package Provides

• Zero-config TypeScript API and React Native chat UI
• Streaming response callbacks
• Dark/light mode
• Chat history in component state
• Abort generation
• Temperature and max token options
• New Architecture-ready native module surface
• Kotlin + JNI bridge on Android
• Objective-C++/Swift bridge on iOS
• Shared C++ inference runtime facade
• Bundled compressed TinyLlama model
• First-run model install into app-private storage
• llama.cpp-backed local inference

API

import { LocalAI } from 'react-native-local-ai';

await LocalAI.initialize();

const text = await LocalAI.chat({
  message: 'Hello',
  temperature: 0.7,
  maxTokens: 256
});

await LocalAI.chatStream({
  message: 'Tell me a joke',
  onToken(token) {
    console.log(token);
  }
});

await LocalAI.stopGeneration();

Components

import { AIChat, AIMessage, AIInput, AITypingIndicator } from 'react-native-local-ai';

<AIChat /> is the plug-and-play screen component. The smaller components are exported for custom chat layouts.

Offline Model Install

The npm package stays small enough to publish, then installs TinyLlama during npm install. The postinstall script downloads the TinyLlama GGUF, verifies its checksum, and writes this compressed asset into the package directory:

assets/local-ai/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf.gz

When an app calls LocalAI.initialize(), the native module installs the model automatically:

• Android copies assets/local-ai/*.gguf if present, otherwise decompresses *.gguf.gz into context.filesDir/local-ai/.
• iOS copies a bundled .gguf if present, otherwise decompresses *.gguf.gz into Application Support.

The model download can be skipped in CI or custom packaging with:

REACT_NATIVE_LOCAL_AI_SKIP_MODEL_DOWNLOAD=1 npm install

If install scripts are disabled, run the installer before building the native app:

npx react-native-local-ai-install-model

To refresh the local model and llama.cpp vendor sources before publishing:

npm run setup:local-ai

That prepares:

• assets/local-ai/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf
• assets/local-ai/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf.gz
• third_party/llama.cpp/

The raw .gguf and generated .gguf.gz files are excluded from published packages so npm does not reject the tarball.

Architecture

React Native UI
  -> LocalAI TypeScript API
  -> TurboModule / NativeModule surface
  -> Kotlin + JNI / Objective-C++ + Swift
  -> Shared C++ LocalAIRuntime
  -> llama.cpp
  -> Bundled TinyLlama Q4 GGUF model

Verification

npm run build
npm run typecheck
npm test
npm_config_cache=.npm-cache npm pack --dry-run

Notes

• iOS and Android ARM64 are the intended production targets.
• The runtime is designed for background inference threads, mmap model loading, and KV cache reuse.
• Developers using the package should not pass model paths. Model copy/load is owned internally by native code.