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

rizalibnu · 2026-01-27T07:56:42Z

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?

Yes
No

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

// 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)
New feature (change which adds functionality)
Documentation update (improves or adds clarity to existing documentation)
Other (chores, tests, code style improvements etc.)

Tested on

iOS
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 feat: add bare React Native LLM chat example app #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

Related issues

Closes #549

Checklist

I have performed a self-review of my code
I have commented my code, particularly in hard-to-understand areas
I have updated the documentation accordingly
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.

Add modular resource fetcher adapters to support both Expo and bare React Native environments. ## New Packages ### @rn-executorch/expo-adapter - Expo-based resource fetcher using expo-file-system - Supports asset bundles, local files, and remote downloads - Download management with pause/resume/cancel capabilities ### @rn-executorch/bare-adapter - Bare React Native resource fetcher using RNFS and background downloader - Supports all platform-specific file operations - Background download support with proper lifecycle management ## Core Changes - Refactor ResourceFetcher to use adapter pattern - Add initExecutorch() and cleanupExecutorch() for adapter management - Export adapter interfaces and utilities - Update LLM controller to support new resource fetching ## App Updates - Update computer-vision, llm, speech-to-text, text-embeddings apps - Add adapter initialization to each app - Update dependencies to use workspace packages

Add a complete bare React Native example app demonstrating LLM integration with react-native-executorch. ## App: llm_bare ### Features - Simple chat UI for LLM interactions - Model loading with progress indicator - Real-time streaming responses - Send/stop generation controls - Auto-scrolling message history ### Stack - **Framework**: React Native 0.81.5 (bare/CLI) - **LLM**: Uses LLAMA3_2_1B_SPINQUANT model - **Adapter**: @rn-executorch/bare-adapter - **Dependencies**: Minimal deps, only essential packages ### Platform Configuration #### iOS - Bridging header for RNBackgroundDownloader - Background URL session handling in AppDelegate - Background modes (fetch, processing) - Xcode project configuration #### Android - Required permissions for background downloads - Foreground service configuration - Network state access - Proper manifest configuration ### Infrastructure - Babel configuration for export namespace transform This serves as a reference implementation for using react-native-executorch in bare React Native environments (non-Expo).

…r better control

…oads

…er-adapters

…tion

…ions

msluszniak · 2026-01-27T09:46:56Z

Lint CI fails (you don't need to worry about the second failing CI ;)). Please could you fix the errors from this CI?

rizalibnu · 2026-01-27T10:20:24Z

@msluszniak I’m not able to reproduce the lint CI failure locally — everything passes on my side.

I’ll take a closer look and investigate further to see what might be causing the discrepancy (environment, cache, or config differences). I’ll follow up with a fix or more details as soon as I find the root cause.

msluszniak · 2026-01-27T10:27:22Z

@rizalibnu Sure thing, maybe the configuration of the CI itself does not work with as it should. We'll also look at this, don't worry :)

rizalibnu · 2026-01-27T14:12:55Z

@msluszniak Found the issue 👍
CI was failing because react-native-executorch types come from lib/typescript, which isn’t built on a fresh run. It worked locally since I already had the build artifacts.

Fixed by adding a build step before adapter type checks and bumped Node to 22 in .nvmrc due to an ESM-only dependency (arktype via react-native-builder-bob).

…package.json for bare and expo adapters

…r for better error handling

msluszniak · 2026-01-27T16:59:27Z

package.json

+      "apps/computer-vision",
+      "apps/llm",
+      "apps/speech",
+      "apps/text-embeddings"


Why we need to expanded apps/*

@msluszniak We need to expand apps/* because apps/bare_rn in PR #763 must be excluded from the Yarn workspace. An alternative is explicitly excluding it in package.json as shown below.

"workspaces": [ "apps/*", "!apps/bare_rn" ]

Which approach do you prefer?

Personally, I prefer the alternative, because if we add another apps in the future, we don't need to remember to update this file. But I would like to know others opinion, cc: @chmjkb @mkopcins

I agree with the alternative 👍
Using apps/* with an explicit exclusion is more future-proof.
Should we apply the same glob + exclusion pattern to packages/ as well for consistency?

"workspaces": { "packages": [ "packages/*", "apps/*", "!apps/bare_rn" ] }

I think I'm on the alternative side as we likely won't add much bare RN example apps in the future.

I’ve applied the glob pattern to apps/ and packages/. Please re-review. @msluszniak @chmjkb

msluszniak · 2026-01-27T17:02:09Z

packages/expo-resource-fetcher/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@rn-executorch/expo-adapter",
+  "version": "0.1.0",


Do we want to have version of adapters to be divergent from version of React Native ExecuTorch cc: @chmjkb @mkopcins ?

I think that's fine. We just need to keep in mind to add a compatibility table, if some version is not compatible at some point. We can also make sure that RNET is a peer dependency of the adapters so we can narrow down on the versions there.

I just remember from one project, that we wanted at some point unify the versions of packages in monorepo, but it was to late since we started with the approach as here. Same thing as Apple did with OS versions on multiple devices ;p

That’s a fair concern.

While independent adapter releases are useful early on, IMO I think a good compromise might be to align major/minor versions between adapters and RNET, while allowing independent patch releases. This keeps compatibility clear for users without blocking adapter-only fixes.

Happy to follow whatever versioning direction the maintainers prefer.

chmjkb · 2026-01-29T10:55:50Z

apps/llm/tsconfig.json

    "paths": {
-      "react-native-executorch": ["../../packages/react-native-executorch/src"]
+      "react-native-executorch": ["../../packages/react-native-executorch/src"],
+      "@rn-executorch/expo-adapter": ["../../packages/expo-adapter/src"]


nit: we're likely going to call the package react-native-executorch/expo-resource-fetcher or react-native-executorch/bare-resource-fetcher, so let's stick to that naming 👍🏻

Updated. Please re-review. @chmjkb

chmjkb · 2026-01-29T11:25:17Z

package.json

+      "apps/computer-vision",
+      "apps/llm",
+      "apps/speech",
+      "apps/text-embeddings"


I think I'm on the alternative side as we likely won't add much bare RN example apps in the future.

chmjkb · 2026-01-29T11:38:46Z

packages/react-native-executorch/src/index.ts

+}
+
+export function cleanupExecutorch() {
+  ResourceFetcher.setAdapter(null as unknown as ResourceFetcherAdapter);


Maybe it would be a tiny bit cleaner if we had a resetAdapter or something like this exposed from ResourceFetcher

I’ve added resetAdapter. Please re-review. @chmjkb

chmjkb · 2026-01-29T12:20:36Z

packages/bare-adapter/README.md

+- Projects that need true background downloads
+- Projects requiring direct native filesystem access
+
+This adapter uses `@dr.pogodin/react-native-fs` and `@kesha-antonov/react-native-background-downloader` for enhanced file operations and background download support.


Maybe it would be cool to link here to their installation steps

Updated. Please re-review. @chmjkb

chmjkb · 2026-01-29T12:44:08Z

packages/bare-adapter/src/ResourceFetcherUtils.ts

+
+  export async function createDirectoryIfNoExists() {
+    if (!(await checkFileExists(RNEDirectory))) {
+      await RNFS.mkdir(RNEDirectory);


Can we try catch here and re-throw rnexecutorch erorr?

Updated. Please re-review. @chmjkb

chmjkb · 2026-01-29T12:52:21Z

packages/expo-resource-fetcher/src/ResourceFetcherUtils.ts

+  extendedInfo: ResourceSourceExtended;
+}
+
+export namespace ResourceFetcherUtils {


Is there a reason for exporting this as a namespace?

@chmjkb It follows the original implementation in the existing codebase. I kept the same pattern to stay consistent and avoid unnecessary refactors.
https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/utils/ResourceFetcherUtils.ts#L50

chmjkb · 2026-01-29T13:11:41Z

packages/react-native-executorch/src/utils/ResourceFetcher.ts

+  pauseFetching(...sources: ResourceSource[]): Promise<void>;
+  resumeFetching(...sources: ResourceSource[]): Promise<void>;
+  cancelFetching(...sources: ResourceSource[]): Promise<void>;
+  listDownloadedFiles(): Promise<string[]>;
+  listDownloadedModels(): Promise<string[]>;
+  deleteResources(...sources: ResourceSource[]): Promise<void>;
+  getFilesTotalSize(...sources: ResourceSource[]): Promise<number>;
+  readAsString(path: string): Promise<string>;


I'm wondering if these should be enforced, in the library internals, we only use fetch(), meaning that in case where the user wants to implement his own resource fetcher, he only has to implement fetch() for the library internals to work. The other methods are just for convenience. We should either add a JSDoc here saying that or we should remove them from this interface completely. cc @mkopcins, wdyt?

yes, we should require the bare minimum for the fetcher to work and mark other method as optional to make implementing custom fetcher as simple as possible

I’ve simplified the interface to include only the methods that are actually used. Please re-review. @mkopcins @chmjkb

Add explicit resetAdapter() method to ResourceFetcher class for cleaner API. - Add resetAdapter() static method that sets adapter to null - Update cleanupExecutorch() to use resetAdapter() instead of type assertion hack - Update error message to reference new package names (@react-native-executorch/*) This provides a cleaner, type-safe way to reset the adapter without requiring "null as unknown as ResourceFetcherAdapter" type assertion.

…ecking and cleaning

rizalibnu and others added 13 commits January 23, 2026 09:07

Merge branch 'main' into feat/resource-fetcher-adapters

109755b

feat: enhance resource fetcher with error handling and new methods fo…

748290f

…r better control

chore: exclude llm_bare app from workspace

139926a

feat: integrate MMKV for persistent state storage in background downl…

d52df47

…oads

Merge remote-tracking branch 'upstream/main' into feat/resource-fetch…

916feb1

…er-adapters

chore: temporarily remove bare RN LLM example app for code review

8f6fa82

chore: revert formatting in inference time and memory usage documenta…

a9d16b4

…tion

chore: remove bare app directories from .gitignore

68dab92

chore: update react-native-executorch dependency to allow any version

529e49e

docs: add bare and expo adapters with installation and usage instruct…

d324a74

…ions

chore: bump version to 0.8.0 in package.json

96150b9

rizalibnu changed the title ~~feat: add modular resource fetcher adapters for Expo and React Native~~ feat: add modular resource fetcher adapters for Expo and bare React Native Jan 27, 2026

IgorSwat requested a review from chmjkb January 27, 2026 08:42

mkopcins self-requested a review January 27, 2026 09:02

chore: add react-native-executorch as a dependency to adapters

af4ca6a

chore: add RNFS to the spell check wordlist

73d1957

rizalibnu marked this pull request as draft January 27, 2026 13:22

rizalibnu marked this pull request as ready for review January 27, 2026 14:06

rizalibnu added 2 commits January 27, 2026 21:56

chore: update Node version in .nvmrc and adjust typecheck scripts in …

3638069

…package.json for bare and expo adapters

chore: replace generic error with RnExecutorchError in ResourceFetche…

359427b

…r for better error handling

rizalibnu force-pushed the feat/resource-fetcher-adapters branch from 72914c0 to 359427b Compare January 27, 2026 14:57

chore: move yarn prepare from adapter typecheck scripts to CI workflow

614835e

rizalibnu mentioned this pull request Jan 27, 2026

feat: add bare React Native LLM chat example app #763

Open

12 tasks

msluszniak added the feature PRs that implement a new feature label Jan 28, 2026

msluszniak reviewed Jan 28, 2026

View reviewed changes

chmjkb requested changes Jan 29, 2026

View reviewed changes

rizalibnu added 9 commits January 30, 2026 05:20

Merge branch 'main' into feat/resource-fetcher-adapters

3db78aa

chore: update workspaces to use wildcard patterns for packages and apps

de85d45

fix: handle directory creation errors in ResourceFetcherUtils

1dc8951

refactor: rename adapters to resource-fetcher packages

aa193e8

refactor: simplify ResourceFetcherAdapter interface

43a1147

build: configure TypeScript compilation for resource-fetcher packages

89ea1ea

refactor: streamline Typecheck step in CI workflow

0104367

refactor: update CI workflow and package scripts for improved type ch…

ac19ef5

…ecking and cleaning

rizalibnu requested review from chmjkb and msluszniak January 30, 2026 10:48

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

rizalibnu commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Introduces a breaking change?

Type of change

Tested on

Testing instructions

Screenshots

Related issues

Checklist

Additional notes

Uh oh!

msluszniak commented Jan 27, 2026

Uh oh!

rizalibnu commented Jan 27, 2026

Uh oh!

msluszniak commented Jan 27, 2026

Uh oh!

rizalibnu commented Jan 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msluszniak Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rizalibnu Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rizalibnu Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chmjkb Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

rizalibnu commented Jan 27, 2026 •

edited

Loading

msluszniak Jan 28, 2026 •

edited

Loading

rizalibnu Jan 28, 2026 •

edited

Loading

rizalibnu Feb 1, 2026 •

edited

Loading

chmjkb Jan 28, 2026 •

edited

Loading