feat!: add modular resource fetcher adapters for Expo and bare React Native (#759)

## Description

This PR introduces modular resource fetcher adapters to support both
Expo and bare React Native environments, replacing the previous
monolithic approach with a flexible, platform-specific architecture.

**Key Changes**
New Adapter Packages:

- @rn-executorch/expo-adapter: Resource fetcher for Expo projects using
expo-file-system and expo-asset
- @rn-executorch/bare-adapter: Resource fetcher for bare React Native
projects using @dr.pogodin/react-native-fs and
@kesha-antonov/react-native-background-downloader

**Initialization Changes:**

- Added initExecutorch() function that requires explicit adapter
selection
- Users must now choose and configure the appropriate adapter for their
project type
- Provides better separation of concerns and platform-specific
optimizations

**Documentation Updates:**
- Created individual README.md files for each adapter package

### Introduces a breaking change?

- [x] Yes
- [ ] No

**Migration Required:**
Users must now explicitly initialize the library with a resource fetcher
adapter:

```typescript
// Before (no initialization needed)
import { useLLM } from 'react-native-executorch';

// After (required initialization)
import { initExecutorch, useLLM } from 'react-native-executorch';
import { ExpoResourceFetcher } from '@rn-executorch/expo-adapter'; // or BareResourceFetcher

initExecutorch({
  resourceFetcher: ExpoResourceFetcher,
});
```

### Type of change

- [ ] Bug fix (change which fixes an issue)
- [x] New feature (change which adds functionality)
- [x] Documentation update (improves or adds clarity to existing
documentation)
- [ ] Other (chores, tests, code style improvements etc.)

### Tested on

- [x] iOS
- [x] Android

### Testing instructions

**For Expo projects:**

- Install dependencies: `yarn add @rn-executorch/expo-adapter
expo-file-system expo-asset`
- Initialize: `initExecutorch({ resourceFetcher: ExpoResourceFetcher })`
- Run existing LLM example app to verify model downloads work correctly

**For bare React Native projects:**

- Install dependencies: `yarn add @rn-executorch/bare-adapter
@dr.pogodin/react-native-fs
@kesha-antonov/react-native-background-downloader`
- Initialize: `initExecutorch({ resourceFetcher: BareResourceFetcher })`
- Run the bare React Native example app in PR #763

> Note: A separate PR will add a dedicated bare React Native example app
to make this PR easier to review. The Expo example apps can be used to
verify the Expo adapter functionality.

### Screenshots

<!-- Add screenshots here, if applicable -->

### Related issues

Closes #549 

### Checklist

- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have updated the documentation accordingly
- [x] My changes generate no new warnings

### Additional notes

**Why This Change:**

- Different React Native environments have different filesystem APIs and
c
- apabilities
- Expo projects benefit from using Expo's managed filesystem APIs
- Bare React Native projects can leverage native libraries with
background download support
- Modular architecture allows for better platform-specific optimizations
- Enables future extensibility for other environments (e.g., React
Native Windows, macOS)

**Split Into Multiple PRs:**
To make review easier, this work has been split:

- This PR: Core adapter infrastructure and Expo adapter implementation
- Follow-up PR: Bare React Native example app demonstrating the bare
adapter usage

BREAKING CHANGE: `initExecutorch()` with explicit adapter selection is
now required before using any react-native-executorch hooks. Users must
install and configure either `@rn-executorch/expo-adapter` or
`@rn-executorch/bare-adapter` depending on their project type.

---------

Co-authored-by: Mateusz Słuszniak <mateusz.sluszniak@swmansion.com>
Co-authored-by: Mateusz Sluszniak <56299341+msluszniak@users.noreply.github.com>
Co-authored-by: Jakub Chmura <92989966+chmjkb@users.noreply.github.com>

Author: 3 people

.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]);