⚠️ DEPRECATION NOTICE
As of July 2025, this project is no longer actively maintained. Whilereact-native-transformerssuccessfully enables on-device inference of Hugging Face transformer models in React Native and Expo apps, I haven't found a strong or consistent use case to justify continued development.If you find this project useful and are interested in taking over its maintenance, feel free to fork it or reach out via GitHub. Contributions are still welcome, but this repository is now considered archived in terms of active development.
Run Hugging Face transformer models directly on your React Native and Expo applications with on-device inference. No cloud service required!
react-native-transformers empowers your mobile applications with AI capabilities by running transformer models directly on the device. This means your app can generate text, answer questions, and process language without sending data to external servers - enhancing privacy, reducing latency, and enabling offline functionality.
Built on top of ONNX Runtime, this library provides a streamlined API for integrating state-of-the-art language models into your React Native and Expo applications with minimal configuration.
- On-device inference: Run AI models locally without requiring an internet connection
- Privacy-focused: Keep user data on the device without sending it to external servers
- Optimized performance: Leverages ONNX Runtime for efficient model execution on mobile CPUs
- Simple API: Easy-to-use interface for model loading and inference
- Expo compatibility: Works seamlessly with both Expo managed and bare workflows
npm install onnxruntime-react-native# React-Native
npm install react-native-transformers
# Expo
npx expo install react-native-transformersReact Native CLI
Link the onnxruntime-react-native library:
npx react-native link onnxruntime-react-nativeExpo
Add the Expo plugin configuration in app.json or app.config.js:
{ "expo": { "plugins": ["onnxruntime-react-native"] } }Add the babel-plugin-transform-import-meta plugin to your Babel configuration:
// babel.config.jsmodule.exports={// ... your existing configplugins: [// ... your existing plugins'babel-plugin-transform-import-meta',],};You can follow this document to create config file, and you need to run npx expo start --clear to clear the Metro bundler cache.
For development and testing, it's required to use a development client instead of Expo Go due to the native code of ONNX Runtime and react-native-transformers.
You can set up a development client using one of these methods:
- EAS Development Build: Create a custom development client using EAS Build
- Expo Prebuild: Eject to a bare workflow to access native code
importReact,{useState,useEffect}from'react';import{View,Text,Button}from'react-native';import{Pipeline}from'react-native-transformers';exportdefaultfunctionApp(){const[output,setOutput]=useState('');const[isLoading,setIsLoading]=useState(false);const[isModelReady,setIsModelReady]=useState(false);// Load model on component mountuseEffect(()=>{loadModel();},[]);constloadModel=async()=>{setIsLoading(true);try{// Load a small Llama modelawaitPipeline.TextGeneration.init('Felladrin/onnx-Llama-160M-Chat-v1','onnx/decoder_model_merged.onnx',{// The fetch function is required to download model filesfetch: async(url)=>{// In a real app, you might want to cache the downloaded filesconstresponse=awaitfetch(url);returnresponse.url;},});setIsModelReady(true);}catch(error){console.error('Error loading model:',error);alert('Failed to load model: '+error.message);}finally{setIsLoading(false);}};constgenerateText=()=>{setOutput('');// Generate text from the prompt and update the UI as tokens are generatedPipeline.TextGeneration.generate('Write a short poem about programming:',(text)=>setOutput(text));};return(<Viewstyle={{padding: 20}}><Buttontitle={isModelReady ? 'Generate Text' : 'Load Model'}onPress={isModelReady ? generateText : loadModel}disabled={isLoading}/><Textstyle={{marginTop: 20}}>{output||'Generated text will appear here'}</Text></View>);}For Expo applications, use expo-file-system to download models with progress tracking:
import*asFileSystemfrom'expo-file-system';import{Pipeline}from'react-native-transformers';// In your model loading functionawaitPipeline.TextGeneration.init('model-repo','model-file',{fetch: async(url)=>{constlocalPath=FileSystem.cacheDirectory+url.split('/').pop();// Check if file already existsconstfileInfo=awaitFileSystem.getInfoAsync(localPath);if(fileInfo.exists){console.log('Model already downloaded, using cached version');returnlocalPath;}// Download file with progress trackingconstdownloadResumable=FileSystem.createDownloadResumable(url,localPath,{},(progress)=>{constpercentComplete=progress.totalBytesWritten/progress.totalBytesExpectedToWrite;console.log(`Download progress: ${(percentComplete*100).toFixed(1)}%`);});constresult=awaitdownloadResumable.downloadAsync();returnresult?.uri;},});react-native-transformers works with ONNX-formatted models from Hugging Face. Here are some recommended models based on size and performance:
| Model | Type | Size | Description |
|---|---|---|---|
| Felladrin/onnx-Llama-160M-Chat-v1 | Text Generation | ~300MB | Small Llama model (160M parameters) |
| microsoft/Phi-3-mini-4k-instruct-onnx-web | Text Generation | ~1.5GB | Microsoft's Phi-3-mini model |
| Xenova/distilgpt2_onnx-quantized | Text Generation | ~165MB | Quantized DistilGPT-2 |
| Xenova/tiny-mamba-onnx | Text Generation | ~85MB | Tiny Mamba model |
| Xenova/all-MiniLM-L6-v2-onnx | Text Embedding | ~80MB | Sentence embedding model |
For detailed API documentation, please visit our TypeDoc documentation.
Contributions are welcome! See the contributing guide to learn how to contribute to the repository and the development workflow.
This project is licensed under the MIT License. See the LICENSE file for details.
- ONNX Runtime for efficient model execution on mobile devices
- @huggingface/transformers for transformer model implementations
- Hugging Face for providing pre-trained models and model hosting