feat!: add modular resource fetcher adapters for Expo and bare React Native

.cspell-wordlist.txt

@@ -108,3 +108,7 @@ sublist
 TTFT
 timestamping
 logprob
+RNFS
+pogodin
+kesha
+antonov

.cspell.json

@@ -1,7 +1,7 @@
 {
   "version": "0.2",
   "language": "en",
-  "ignorePaths": ["**/node_modules", "**/Pods"],
+  "ignorePaths": ["**/node_modules", "**/Pods", "**/readmes/**"],
   "dictionaryDefinitions": [
     {
       "name": "project-words",

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
         run: yarn lint
 
       - name: Typecheck files
-        run: yarn typecheck
+        run: yarn workspaces foreach --all --topological-dev run prepare && yarn typecheck
 
   build-library:
     runs-on: ubuntu-latest
@@ -35,7 +35,5 @@ jobs:
       - name: Setup
         uses: ./.github/actions/setup
 
-      - name: Build package
-        run: |
-          cd packages/react-native-executorch
-          yarn prepare
+      - name: Build all packages
+        run: yarn workspaces foreach --all --topological-dev run prepare

.nvmrc

@@ -1 +1 @@
-v20
+v22

README.md

@@ -76,6 +76,15 @@ React Native ExecuTorch is powering [Private Mind](https://privatemind.swmansion
 ```bash
 # Install the package
 yarn add react-native-executorch
+
+# If you use expo, please add these packages for resource fetching:
+yarn add @react-native-executorch/expo-adapter
+yarn add expo-file-system expo-asset
+
+#if you use bare React Native project use these packages:
+yarn add @react-native-executorch/bare-adapter
+yarn add @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
+
 # Depending on the platform, choose either iOS or Android
 yarn expo run:< ios | android >
 ```
@@ -88,8 +97,14 @@ Add this to your component file:
 import {
   useLLM,
   LLAMA3_2_1B,
-  Message
+  Message,
+  initExecutorch,
 } from 'react-native-executorch';
+import { ExpoResourceFetcher } from '@react-native-executorch/expo-resource-fetcher';
+
+initExecutorch({
+  resourceFetcher: ExpoResourceFetcher,
+});
 
 function MyComponent() {
   // Initialize the model 🚀

apps/computer-vision/app/_layout.tsx

@@ -1,4 +1,7 @@
 import { Drawer } from 'expo-router/drawer';
+import { initExecutorch } from 'react-native-executorch';
+import { ExpoResourceFetcher } from '@react-native-executorch/expo-resource-fetcher';
+
 import ColorPalette from '../colors';
 import React, { useState } from 'react';
 import { Text, StyleSheet, View } from 'react-native';
@@ -10,6 +13,10 @@ import {
 } from '@react-navigation/drawer';
 import { GeneratingContext } from '../context';
 
+initExecutorch({
+  resourceFetcher: ExpoResourceFetcher,
+});
+
 interface CustomDrawerProps extends DrawerContentComponentProps {
   isGenerating: boolean;
 }

apps/computer-vision/package.json

@@ -11,7 +11,8 @@
     "lint": "eslint . --ext .ts,.tsx --fix"
   },
   "dependencies": {
-    "@react-native/metro-config": "^0.76.3",
+    "@react-native-executorch/expo-resource-fetcher": "workspace:*",
+    "@react-native/metro-config": "^0.81.5",
     "@react-navigation/drawer": "^7.3.9",
     "@react-navigation/native": "^7.1.6",
     "@shopify/react-native-skia": "2.2.12",
@@ -21,7 +22,7 @@
     "expo-linking": "~8.0.10",
     "expo-router": "~6.0.17",
     "expo-status-bar": "~3.0.9",
-    "metro-config": "^0.81.0",
+    "metro-config": "^0.81.5",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "react-native-device-info": "^14.0.4",

apps/computer-vision/tsconfig.json

@@ -9,7 +9,10 @@
     "customConditions": ["react-native"],
     "noEmit": true,
     "paths": {
-      "react-native-executorch": ["../../packages/react-native-executorch/src"]
+      "react-native-executorch": ["../../packages/react-native-executorch/src"],
+      "@react-native-executorch/expo-resource-fetcher": [
+        "../../packages/expo-resource-fetcher/src"
+      ]
     }
   }
 }

apps/llm/app/_layout.tsx

@@ -1,15 +1,20 @@
 import { Drawer } from 'expo-router/drawer';
+import { initExecutorch } from 'react-native-executorch';
+import { ExpoResourceFetcher } from '@react-native-executorch/expo-resource-fetcher';
 import ColorPalette from '../colors';
 import React, { useState } from 'react';
 import { Text, StyleSheet, View } from 'react-native';
-
 import {
   DrawerContentComponentProps,
   DrawerContentScrollView,
   DrawerItemList,
 } from '@react-navigation/drawer';
 import { GeneratingContext } from '../context';
 
+initExecutorch({
+  resourceFetcher: ExpoResourceFetcher,
+});
+
 interface CustomDrawerProps extends DrawerContentComponentProps {
   isGenerating: boolean;
 }

apps/llm/app/llm/index.tsx

@@ -34,7 +34,7 @@ function LLMScreen() {
 
   useEffect(() => {
     if (llm.error) {
-      console.log('LLM error:', llm.error);
+      console.error('LLM error:', llm.error);
     }
   }, [llm.error]);
 

apps/llm/app/llm_structured_output/index.tsx

@@ -119,7 +119,7 @@ function LLMScreen() {
 
   useEffect(() => {
     if (llm.error) {
-      console.log('LLM error:', llm.error);
+      console.error('LLM error:', llm.error);
     }
   }, [llm.error]);
 

apps/llm/app/llm_tool_calling/index.tsx

@@ -61,7 +61,7 @@ function LLMToolCallingScreen() {
 
   useEffect(() => {
     if (llm.error) {
-      console.log('LLM error:', llm.error);
+      console.error('LLM error:', llm.error);
     }
   }, [llm.error]);
 

apps/llm/app/voice_chat/index.tsx

@@ -98,6 +98,18 @@ function VoiceChatScreen() {
     }
   };
 
+  useEffect(() => {
+    if (llm.error) {
+      console.error('LLM error:', llm.error);
+    }
+  }, [llm.error]);
+
+  useEffect(() => {
+    if (speechToText.error) {
+      console.error('speechToText error:', speechToText.error);
+    }
+  }, [speechToText.error]);
+
   return !llm.isReady || !speechToText.isReady ? (
     <Spinner
       visible={!llm.isReady || !speechToText.isReady}

apps/llm/package.json

@@ -11,7 +11,8 @@
     "lint": "eslint . --ext .ts,.tsx --fix"
   },
   "dependencies": {
-    "@react-native/metro-config": "^0.76.3",
+    "@react-native-executorch/expo-resource-fetcher": "workspace:*",
+    "@react-native/metro-config": "^0.81.5",
     "@react-navigation/drawer": "^7.3.9",
     "@react-navigation/native": "^7.1.6",
     "expo": "^54.0.27",
@@ -22,7 +23,7 @@
     "expo-linking": "~8.0.10",
     "expo-router": "~6.0.17",
     "expo-status-bar": "~3.0.9",
-    "metro-config": "^0.81.0",
+    "metro-config": "^0.81.5",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "react-native-audio-api": "^0.8.2",

apps/llm/tsconfig.json

@@ -9,7 +9,10 @@
     "customConditions": ["react-native"],
     "noEmit": true,
     "paths": {
-      "react-native-executorch": ["../../packages/react-native-executorch/src"]
+      "react-native-executorch": ["../../packages/react-native-executorch/src"],
+      "@react-native-executorch/expo-resource-fetcher": [
+        "../../packages/expo-resource-fetcher/src"
+      ]
     }
   }
 }

apps/speech/App.tsx

@@ -5,6 +5,12 @@ import { SpeechToTextScreen } from './screens/SpeechToTextScreen';
 import ColorPalette from './colors';
 import ExecutorchLogo from './assets/executorch.svg';
 import { Quiz } from './screens/Quiz';
+import { initExecutorch } from 'react-native-executorch';
+import { ExpoResourceFetcher } from '@react-native-executorch/expo-resource-fetcher';
+
+initExecutorch({
+  resourceFetcher: ExpoResourceFetcher,
+});
 
 export default function App() {
   const [currentScreen, setCurrentScreen] = useState<

apps/speech/package.json

@@ -11,12 +11,13 @@
     "lint": "eslint . --ext .ts,.tsx --fix"
   },
   "dependencies": {
-    "@react-native/metro-config": "^0.76.3",
+    "@react-native-executorch/expo-resource-fetcher": "workspace:*",
+    "@react-native/metro-config": "^0.81.5",
     "buffer": "^6.0.3",
     "expo": "^54.0.27",
     "expo-font": "~14.0.10",
     "expo-status-bar": "~3.0.9",
-    "metro-config": "^0.81.0",
+    "metro-config": "^0.81.5",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "react-native-audio-api": "0.11.3",

apps/speech/tsconfig.json

@@ -9,7 +9,10 @@
     "customConditions": ["react-native"],
     "noEmit": true,
     "paths": {
-      "react-native-executorch": ["../../packages/react-native-executorch/src"]
+      "react-native-executorch": ["../../packages/react-native-executorch/src"],
+      "@react-native-executorch/expo-resource-fetcher": [
+        "../../packages/expo-resource-fetcher/src"
+      ]
     }
   }
 }

apps/text-embeddings/app/_layout.tsx

@@ -1,4 +1,6 @@
 import { Drawer } from 'expo-router/drawer';
+import { initExecutorch } from 'react-native-executorch';
+import { ExpoResourceFetcher } from '@react-native-executorch/expo-resource-fetcher';
 import ColorPalette from '../colors';
 import React, { useState } from 'react';
 import { Text, StyleSheet, View } from 'react-native';
@@ -10,6 +12,10 @@ import {
 } from '@react-navigation/drawer';
 import { GeneratingContext } from '../context';
 
+initExecutorch({
+  resourceFetcher: ExpoResourceFetcher,
+});
+
 interface CustomDrawerProps extends DrawerContentComponentProps {
   isGenerating: boolean;
 }

apps/text-embeddings/package.json

@@ -14,6 +14,7 @@
     "@react-navigation/native": "*"
   },
   "dependencies": {
+    "@react-native-executorch/expo-resource-fetcher": "workspace:*",
     "@react-navigation/drawer": "^7.3.9",
     "expo": "^54.0.27",
     "expo-constants": "~18.0.11",

apps/text-embeddings/tsconfig.json

@@ -9,7 +9,10 @@
     "customConditions": ["react-native"],
     "noEmit": true,
     "paths": {
-      "react-native-executorch": ["../../packages/react-native-executorch/src"]
+      "react-native-executorch": ["../../packages/react-native-executorch/src"],
+      "@react-native-executorch/expo-resource-fetcher": [
+        "../../packages/expo-resource-fetcher/src"
+      ]
     }
   }
 }

docs/docs/01-fundamentals/01-getting-started.md

@@ -62,7 +62,7 @@ Installation is pretty straightforward, just use your favorite package manager.
   </TabItem>
 </Tabs>
 
-If you're using bare React Native (instead of a managed Expo project), you also need to install Expo Modules because the underlying implementation relies on expo-file-system. Since expo-file-system is an Expo package, bare React Native projects need **Expo Modules** to properly integrate and use it. The link provided (https://docs.expo.dev/bare/installing-expo-modules/) offers guidance on setting up Expo Modules in a bare React Native environment.
+Our library offers support for both bare React Native and Expo projects. Please follow the instructions from [Loading models section](./02-loading-models.md) to make sure you setup your project correctly. We encourage you to use Expo project if possible. If you are planning to migrate from bare React Native to Expo project, the link (https://docs.expo.dev/bare/installing-expo-modules/) offers a guidance on setting up Expo Modules in a bare React Native environment.
 
 If you plan on using your models via require() instead of fetching them from a url, you also need to add following lines to your `metro.config.js`:
 

docs/docs/01-fundamentals/02-loading-models.md

@@ -4,6 +4,46 @@ title: Loading Models
 
 There are three different methods available for loading model files, depending on their size and location.
 
+## Prerequisites
+
+In our library, you can use two different resource fetching mechanisms. One is implemented using Expo FileSystem, the other one uses external library. We encourage you to use implementation utilizing Expo if possible.
+
+To use the Expo adapter, please add these libraries:
+
+```bash
+yarn add @react-native-executorch/expo-adapter
+yarn add expo-file-system expo-asset
+```
+
+and then add the following code in your React Native app:
+
+```typescript
+import { initExecutorch } from 'react-native-executorch';
+import { ExpoResourceFetcher } from '@react-native-executorch/expo-resource-fetcher';
+
+initExecutorch({
+  resourceFetcher: ExpoResourceFetcher,
+});
+```
+
+If you cannot use Expo in your project, proceed with the following steps:
+
+```bash
+yarn add @react-native-executorch/bare-adapter
+yarn add @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
+```
+
+and
+
+```typescript
+import { initExecutorch } from 'react-native-executorch';
+import { BareResourceFetcher } from '@react-native-executorch/bare-adapter';
+
+initExecutorch({
+  resourceFetcher: BareResourceFetcher,
+});
+```
+
 **1. Load from React Native assets folder (For Files < 512MB)**
 
 ```typescript

docs/docs/01-fundamentals/03-frequently-asked-questions.md

@@ -31,7 +31,7 @@ If your model doesn't support it, you can still work around it using context. Fo
 
 ### Can I use React Native ExecuTorch in bare React Native apps?
 
-To use the library, you need to install Expo Modules first. For a setup guide, refer to [this tutorial](https://docs.expo.dev/bare/installing-expo-modules/). This is because we use Expo File System under the hood to download and manage the model binaries.
+Yes, staring from version `0.8.x` you can use React Native ExecuTorch in bare React Native apps. You just need to use bare React Native resource fetcher instead of Expo one, see: [Loading models section](./02-loading-models.md) for more details.
 
 ### Do you support the old architecture?