feat: on-demand native lib download and optional feature splitting

.cspell-wordlist.txt

@@ -203,6 +203,52 @@ fishjam
 Fishjam
 deinitialize
 Deinitialize
+podspec
+libexecutorch
+libxnnpack
+libvulkan
+libbackend
+libcpuinfo
+flatcc
+Werror
+dlopen
+msluszniak
+DRNE
+libopencv
+Kleidi
+libphonemis
+libreact
+CPLUSPLUSFLAGS
+LDFLAGS
+iphoneos
+iphonesimulator
+xcframework
+xcframeworks
+EEXIST
+RNET
+Unigram
+SIGSEGV
+memcmp
+nullptr
+DANDROID
+venv
+pyyaml
+libkernels
+libthreadpool
+libkleidiai
+kleidiai
+xcodeproj
+prebuilts
+pthreadpool
+libpthreadpool
+DFLATCC
+flatccrt
+Wimplicit
+Wunterminated
+NSURL
+certifi
+zstd
+lintrunner
 fastsam
 promptable
 topk
@@ -212,6 +258,7 @@ Siwis
 SIWIS
 Mateusz
 MATEUSZ
+gitmodules
 BLAZEFACE
 Blazeface
 blazeface

.github/workflows/build-android-llm-example.yml

@@ -19,6 +19,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       WORKING_DIRECTORY: apps/llm
+      # TODO: drop once v0.9.0 is cut and tarballs are attached to the matching Release.
+      RNET_BASE_URL: https://github.com/software-mansion/react-native-executorch/releases/download/v0.9.0-libs-test
     concurrency:
       group: android-${{ github.ref }}
       cancel-in-progress: true

.github/workflows/build-ios-llm-example.yml

@@ -22,6 +22,9 @@ jobs:
     concurrency:
       group: ios-${{ github.ref }}
       cancel-in-progress: true
+    env:
+      # TODO: drop once v0.9.0 is cut and tarballs are attached to the matching Release.
+      RNET_BASE_URL: https://github.com/software-mansion/react-native-executorch/releases/download/v0.9.0-libs-test
     steps:
       - uses: maxim-lobanov/setup-xcode@v1
         with:

.github/workflows/ci.yml

@@ -10,6 +10,9 @@ on:
     types:
       - checks_requested
   workflow_dispatch:
+env:
+  # TODO: drop once v0.9.0 is cut and tarballs are attached to the matching Release.
+  RNET_BASE_URL: https://github.com/software-mansion/react-native-executorch/releases/download/v0.9.0-libs-test
 jobs:
   lint:
     runs-on: ubuntu-latest

.gitignore

@@ -98,6 +98,17 @@ docs/docs/06-api-reference/
 # integration test model assets
 packages/react-native-executorch/common/rnexecutorch/tests/integration/assets/models/
 
+# release artifact staging dir (produced by scripts/package-release-artifacts.sh)
+packages/react-native-executorch/dist-artifacts/
+
+# on-demand native libs (downloaded at postinstall time, not committed)
+packages/react-native-executorch/third-party/android/libs/
+packages/react-native-executorch/third-party/ios/ExecutorchLib.xcframework/
+packages/react-native-executorch/third-party/ios/CoreMLBackend.xcframework/
+packages/react-native-executorch/third-party/ios/XnnpackBackend.xcframework/
+packages/react-native-executorch/third-party/ios/libs/
+packages/react-native-executorch/rne-build-config.json
+
 # custom
 *.tgz
 Makefile

apps/bare-rn/package.json

@@ -45,5 +45,10 @@
   },
   "installConfig": {
     "hoistingLimits": "workspaces"
+  },
+  "react-native-executorch": {
+    "features": [
+      "llm"
+    ]
   }
 }

apps/computer-vision/package.json

@@ -50,5 +50,20 @@
     "babel-preset-expo": "~55.0.16",
     "react-refresh": "^0.18.0"
   },
-  "private": true
+  "private": true,
+  "react-native-executorch": {
+    "features": [
+      "classification",
+      "imageEmbeddings",
+      "instanceSegmentation",
+      "ocr",
+      "objectDetection",
+      "poseEstimation",
+      "semanticSegmentation",
+      "styleTransfer",
+      "textEmbeddings",
+      "textToImage",
+      "verticalOCR"
+    ]
+  }
 }

apps/llm/package.json

@@ -50,5 +50,12 @@
     "babel-preset-expo": "~55.0.16",
     "react-refresh": "^0.18.0"
   },
-  "private": true
+  "private": true,
+  "react-native-executorch": {
+    "features": [
+      "llm",
+      "multimodalLLM",
+      "privacyFilter"
+    ]
+  }
 }

apps/speech/package.json

@@ -37,5 +37,13 @@
     "babel-preset-expo": "~55.0.16",
     "react-refresh": "^0.18.0"
   },
-  "private": true
+  "private": true,
+  "react-native-executorch": {
+    "features": [
+      "llm",
+      "speechToText",
+      "textToSpeech",
+      "vad"
+    ]
+  }
 }

apps/speech/screens/VoiceActivityDetectionScreen.tsx

@@ -8,10 +8,7 @@ import {
   Platform,
 } from 'react-native';
 import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
-import {
-  models,
-  useVAD 
-} from 'react-native-executorch';
+import { models, useVAD } from 'react-native-executorch';
 import FontAwesome from '@expo/vector-icons/FontAwesome';
 import { AudioManager, AudioRecorder } from 'react-native-audio-api';
 import SWMIcon from '../assets/swm_icon.svg';

apps/text-embeddings/package.json

@@ -40,5 +40,11 @@
     "babel-preset-expo": "~55.0.16",
     "react-refresh": "^0.18.0"
   },
-  "private": true
+  "private": true,
+  "react-native-executorch": {
+    "features": [
+      "textEmbeddings",
+      "imageEmbeddings"
+    ]
+  }
 }

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

@@ -122,6 +122,81 @@ Pick the adapter that matches your project. We recommend the Expo adapter when y
   </TabItem>
 </Tabs>
 
+### Configuring backends, libs, and features
+
+On install, `react-native-executorch` runs a `postinstall` script that downloads prebuilt native libraries from the matching GitHub Release and unpacks them under `third-party/`. By default every optional feature is included — which keeps the app binary large. You can trim the install by declaring exactly what you need under `react-native-executorch` in your app's `package.json`. Three optional arrays are supported, and they're all merged into a single set:
+
+```json
+{
+  "react-native-executorch": {
+    "backends": ["xnnpack", "coreml", "vulkan"],
+    "libs": ["opencv", "phonemizer"],
+    "features": ["llm", "textToSpeech", "objectDetection"]
+  }
+}
+```
+
+- **`features`** is the friendly opt-in. List the use\* hooks you'll use; the postinstall expands each one to the backends + libs it needs.
+- **`backends` / `libs`** are the precise opt-in. List the underlying components directly.
+- Omit the whole `react-native-executorch` block to enable everything (largest install, lowest friction).
+- If you mix `features` with `backends`/`libs`, the result is their union.
+
+Recognized **backends**: `xnnpack`, `coreml` (iOS-only), `vulkan` (Android-only).
+Recognized **libs**: `opencv`, `phonemizer`.
+Recognized **features** (one per documented hook):
+
+Each row reflects the union of what at least one model in that family ships today; bump it when a new variant adds a backend.
+
+| Feature                | Pulls in (backends · libs) | What it powers                          |
+| ---------------------- | -------------------------- | --------------------------------------- |
+| `llm`                  | xnnpack · —                | Text-only `useLLM`                      |
+| `multimodalLLM`        | xnnpack, vulkan · opencv   | Vision-language `useLLM` (image inputs) |
+| `privacyFilter`        | xnnpack · —                | `usePrivacyFilter`                      |
+| `speechToText`         | xnnpack, coreml · —        | `useSpeechToText` (Whisper)             |
+| `textToSpeech`         | xnnpack · phonemizer       | `useTextToSpeech` (Kokoro)              |
+| `vad`                  | xnnpack · —                | `useVAD`                                |
+| `textEmbeddings`       | xnnpack · —                | `useTextEmbeddings`                     |
+| `imageEmbeddings`      | xnnpack · opencv           | `useImageEmbeddings`                    |
+| `classification`       | xnnpack, coreml · opencv   | `useClassification`                     |
+| `objectDetection`      | xnnpack, coreml · opencv   | `useObjectDetection`                    |
+| `semanticSegmentation` | xnnpack · opencv           | `useSemanticSegmentation`               |
+| `instanceSegmentation` | xnnpack, coreml · opencv   | `useInstanceSegmentation`               |
+| `ocr`                  | xnnpack · opencv           | `useOCR`                                |
+| `verticalOCR`          | xnnpack · opencv           | `useVerticalOCR`                        |
+| `poseEstimation`       | xnnpack · opencv           | `usePoseEstimation`                     |
+| `styleTransfer`        | xnnpack, coreml · opencv   | `useStyleTransfer`                      |
+| `textToImage`          | xnnpack · opencv           | `useTextToImage`                        |
+| `segmentAnything`      | xnnpack, coreml · opencv   | FastSAM / Segment-Anything hooks        |
+
+Backend platform map:
+
+| Backend   | iOS                                                         | Android                                                   |
+| --------- | ----------------------------------------------------------- | --------------------------------------------------------- |
+| `xnnpack` | ✅ — `XnnpackBackend.xcframework` force-loaded into the app | ✅ — separately-loaded `libxnnpack_executorch_backend.so` |
+| `coreml`  | ✅ — `CoreMLBackend.xcframework` force-loaded into the app  | n/a                                                       |
+| `vulkan`  | n/a                                                         | ✅ — separately-loaded `libvulkan_executorch_backend.so`  |
+
+Lib platform map:
+
+| Lib          | iOS                                | Android                                                  |
+| ------------ | ---------------------------------- | -------------------------------------------------------- |
+| `opencv`     | ✅ (via the `opencv-rne` CocoaPod) | ✅ (static `libopencv_*.a` + KleidiCV HAL on arm64)      |
+| `phonemizer` | ✅ (compiled from in-tree source)  | ✅ (compiled from in-tree source via `add_subdirectory`) |
+
+Source files and native libraries are excluded from compilation when a backend or lib is disabled, so builds that only need LLMs can skip OpenCV and cut tens of megabytes off the final binary.
+
+The postinstall step honors a few environment variables:
+
+| Variable               | Purpose                                                                   |
+| ---------------------- | ------------------------------------------------------------------------- |
+| `RNET_SKIP_DOWNLOAD=1` | Skip the download entirely (for CI with pre-cached libraries).            |
+| `RNET_LIBS_CACHE_DIR`  | Custom cache directory (default: `~/.cache/react-native-executorch/<v>`). |
+| `RNET_TARGET`          | Force a specific target, e.g. `android-arm64-v8a` or `ios`.               |
+| `RNET_NO_X86_64=1`     | Skip the Android x86_64 tarball (handy when only building for a device).  |
+| `GITHUB_TOKEN`         | Required to access draft releases while iterating on a new version.       |
+
+After changing `backends` / `libs` / `features`, re-run `yarn install` (or the equivalent) so the postinstall script regenerates `rne-build-config.json` and re-extracts the right tarballs, then rebuild the native project.
+
 :::warning
 Before using any other API, you must call `initExecutorch` with a resource fetcher adapter at the entry point of your app: