feat: add bare React Native LLM chat example app by rizalibnu · Pull Request #763 · software-mansion/react-native-executorch

rizalibnu · 2026-01-27T19:40:50Z

Description

Adds a new bare React Native example application demonstrating LLM chat functionality using Executorch. This example provides a complete reference implementation for running local LLM inference on mobile devices through a simple chat interface.

Key features:

Local LLM inference using Executorch
Simple chat UI with message history
Model loading and inference pipeline
Error handling and user feedback
Compatible with both iOS and Android

Introduces a breaking change?

Yes
No

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

Navigate to the example directory:

cd apps/bare_rn

Install dependencies:

yarn install

Run on iOS:

npx pod-install
yarn ios

Or run on Android:

yarn android

Verify the app launches and displays the chat interface
Test message sending and model inference (requires model file setup)

Screenshots

Related issues

This PR provides an example app for PR #759

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

This example app was generated using npx @react-native-community/cli@latest init bare_rn --version 0.81.5 --pm yarn and follows bare React Native project structure (not Expo). It serves as a foundational example for developers to understand how to integrate Executorch for on-device LLM inference in their React Native applications.

Why this example is not included in the yarn workspace:

The bare React Native example is maintained outside the yarn workspace structure due to fundamental architectural differences and specific technical issues:

Native Module Resolution Issues with Background Downloader:
Using the workspace monorepo breaks the Android app's integration with @kesha-antonov/react-native-background-downloader. The monorepo's package hoisting and workspace resolution interferes with the native module's ability to properly register and resolve its native components. This causes runtime failures when attempting to download AI models in the background, which is a critical feature for this LLM chat example.
Dependency Isolation: Bare React Native projects have distinct native dependency chains (iOS Pods, Android Gradle) that conflict with the monorepo's package management. The monorepo uses workspaces and hoisting strategies optimized for JavaScript/TypeScript packages, which can interfere with native module resolution.

rizalibnu · 2026-01-28T03:14:55Z

This PR is ready for review, but I’d prefer to proceed after #759 is merged, since this PR includes changes from #759, which makes the diff quite large.

Alternatively, you can review this commit bb65951, which contains the changes after initializing the bare React Native app using @react-native-community/cli@latest

…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  ### 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>

msluszniak · 2026-02-23T11:20:43Z

Hi @rizalibnu, we have successfully merged your changes with adapters 🚀 . Do you want to proceed with this PR or do you want to pass it for us?

rizalibnu · 2026-03-08T08:03:35Z

Hi @msluszniak, sorry for the slow response — I’ve been AFK from OSS for the past two weeks.

I see there has already been good progress on this PR, so feel free to proceed and pass it from your side if that’s easier. Thanks again for the work on merging the adapters 🚀

Hi @rizalibnu, we have successfully merged your changes with adapters 🚀 . Do you want to proceed with this PR or do you want to pass it for us?

msluszniak · 2026-03-08T09:37:53Z

No worries @rizalibnu. I'll progress with the PR and let you know once it will be finished so you can add some suggestions.

msluszniak · 2026-03-10T10:14:31Z

@rizalibnu can you check if this works for you? Specifically, I had a problem with building Android on my mac, and I think that can be due to macOS 26.

Add modular resource fetcher adapters to support both Expo and bare React Native environments. - Expo-based resource fetcher using expo-file-system - Supports asset bundles, local files, and remote downloads - Download management with pause/resume/cancel capabilities - Bare React Native resource fetcher using RNFS and background downloader - Supports all platform-specific file operations - Background download support with proper lifecycle management - 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 - 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. - Simple chat UI for LLM interactions - Model loading with progress indicator - Real-time streaming responses - Send/stop generation controls - Auto-scrolling message history - **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 - Bridging header for RNBackgroundDownloader - Background URL session handling in AppDelegate - Background modes (fetch, processing) - Xcode project configuration - Required permissions for background downloads - Foreground service configuration - Network state access - Proper manifest configuration - 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

…package.json for bare and expo adapters

…r for better error handling

…y/cli@latest

msluszniak · 2026-03-10T16:56:04Z

I figured out how to handle android correctly so now it works, but needed to change resource fetcher for bare react native a bit, cc: @NorbertKlockiewicz

…egration/assets/models/.gitignore

Keep rocket emoji in the description and 1️⃣/2️⃣/3️⃣ in the quickstart section. Also remove bold from quickstart headings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Align ES, FR, CN, IN, PT readmes with the English README layout: remove emoji prefixes from headings and table of contents, keep :one:/:two:/:three: in quickstart steps, remove bold from step titles. Also add --no-must-find-files to cspell hook so it doesn't fail when all staged .md files are excluded by ignorePaths. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chmjkb · 2026-03-13T11:25:44Z

+      task: {
+        stop: () => RNFS.stopDownload(rnfsDownload.jobId),
+        pause: () => {},
+        resume: () => {},


Please don't silently fail pause / resume. This is very confusing. If RNFS doesn't support this, throw an error saying that the operation is not supported.

Also I think there is a cache file leak on cancel when RNFS.stopDownload is called, the partial file at cacheFileUri is never deleted.

chmjkb

the app now compiles on Android, I'm not sure why but when I enter the app i get the following error:

chmjkb · 2026-03-13T17:50:10Z

the app now compiles on Android, I'm not sure why but when I enter the app i get the following error:

maybe its a problem with my emulator as I verified that this file exists

msluszniak · 2026-03-13T18:31:42Z

the app now compiles on Android, I'm not sure why but when I enter the app i get the following error:

maybe its a problem with my emulator as I verified that this file exists

I'll investigate this on both android emulator and physical device.

msluszniak · 2026-03-16T09:54:01Z

@chmjkb I cannot reproduce this issue neither on my physical device nor android emulator. I added better error and I also added command that will run yarn prepare on packages so there is no need to manually call yarn prepare in packages.

chmjkb

Just make sure to update the error handling page in docs with the new error code

rizalibnu force-pushed the examples/bare-react-native branch from c27a355 to bb65951 Compare January 28, 2026 03:10

rizalibnu marked this pull request as ready for review January 28, 2026 03:15

rizalibnu mentioned this pull request Jan 28, 2026

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

Merged

12 tasks

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

msluszniak added pending response This issue awaits some action labels Feb 23, 2026

msluszniak added this to the v0.8.0 milestone Feb 27, 2026

msluszniak force-pushed the examples/bare-react-native branch from bb65951 to 8816fbc Compare March 3, 2026 13:17

msluszniak self-assigned this Mar 3, 2026

msluszniak force-pushed the examples/bare-react-native branch from b4e11d3 to 295701d Compare March 9, 2026 14:58

rizalibnu and others added 14 commits March 10, 2026 17:54

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

a973890

…r better control

chore: exclude llm_bare app from workspace

3b93bc7

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

8f310c1

…oads

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

93f90ec

chore: remove bare app directories from .gitignore

ebe6836

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

f447454

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

af54de0

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

6cc94d1

…package.json for bare and expo adapters

chore: replace generic error with RnExecutorchError in ResourceFetche…

f2fcd03

…r for better error handling

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

c6f73ec

chore: init bare React Native example app with @react-native-communit…

502b2fc

…y/cli@latest

feat: add bare React Native LLM chat example app

bbc2980

msluszniak force-pushed the examples/bare-react-native branch from 9f75c02 to fe18a04 Compare March 10, 2026 16:54

msluszniak requested review from NorbertKlockiewicz and chmjkb March 10, 2026 16:56

msluszniak and others added 2 commits March 11, 2026 19:07

Delete packages/react-native-executorch/common/rnexecutorch/tests/int…

0b0f83d

…egration/assets/models/.gitignore

chore: remove Readme from bare rn app

f0b3a33

NorbertKlockiewicz approved these changes Mar 12, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

msluszniak and others added 2 commits March 12, 2026 11:23

docs: remove emojis from README headings and table of contents

bb76d97

Keep rocket emoji in the description and 1️⃣/2️⃣/3️⃣ in the quickstart section. Also remove bold from quickstart headings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

msluszniak removed the pending response This issue awaits some action label Mar 12, 2026

chmjkb reviewed Mar 12, 2026

View reviewed changes

Comment thread .gitignore

Comment thread README.md Outdated

msluszniak added 2 commits March 13, 2026 10:39

chore: update READMEs

c2edbf2

chore: align readmes

2539961

msluszniak approved these changes Mar 13, 2026

View reviewed changes

msluszniak requested a review from chmjkb March 13, 2026 09:43

chmjkb requested changes Mar 13, 2026

View reviewed changes

chore: add suggestions from code review

7d1479c

msluszniak requested a review from chmjkb March 13, 2026 13:21

chore: fix android build

7700b7d

chmjkb reviewed Mar 13, 2026

View reviewed changes

Comment thread packages/bare-resource-fetcher/src/ResourceFetcher.ts Outdated

msluszniak added 3 commits March 16, 2026 10:12

chore: make error code specifically for resource fetcher

c7eb2c1

chore: add missing error codes

fab283c

chore: add yarn prepare command for all packages

cdb4af8

chmjkb approved these changes Mar 16, 2026

View reviewed changes

docs: document new error code in documentation

f2979fc

msluszniak merged commit effbfff into software-mansion:main Mar 16, 2026
5 of 6 checks passed

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!

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

Uh oh!

Uh oh!

msluszniak commented Feb 23, 2026

Uh oh!

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

Uh oh!

Uh oh!

msluszniak commented Mar 8, 2026

Uh oh!

msluszniak commented Mar 10, 2026

Uh oh!

msluszniak commented Mar 10, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

chmjkb Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

chmjkb Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

chmjkb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chmjkb commented Mar 13, 2026

Uh oh!

msluszniak commented Mar 13, 2026

Uh oh!

msluszniak commented Mar 16, 2026

Uh oh!

chmjkb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rizalibnu commented Jan 27, 2026 •

edited

Loading

rizalibnu commented Jan 28, 2026 •

edited

Loading

rizalibnu commented Mar 8, 2026 •

edited

Loading