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

.cspell-wordlist.txt

@@ -203,3 +203,32 @@ 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

.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

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

@@ -76,6 +76,42 @@ Installation is pretty straightforward, use your package manager of choice to in
   </TabItem>
 </Tabs>
 
+### Configuring backends and extras
+
+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 opt out of anything you don't need by adding an `extras` array to your app's `package.json`:
+
+```json
+{
+  "react-native-executorch": {
+    "extras": ["xnnpack", "coreml", "vulkan", "opencv", "phonemizer"]
+  }
+}
+```
+
+If the `extras` key is omitted, all five features are enabled. To disable a feature, drop its name from the array.
+
+| Extra        | iOS                                                                         | Android                                                                                       | What it enables                                               |
+| ------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `opencv`     | ✅ (via the `opencv-rne` CocoaPod)                                          | ✅                                                                                            | Computer-vision models (classification, detection, OCR, etc.) |
+| `phonemizer` | ✅                                                                          | ✅                                                                                            | Text-to-speech models                                         |
+| `xnnpack`    | ✅ — `XnnpackBackend.xcframework` force-loaded into the app                 | ✅ — separately-loaded `libxnnpack_executorch_backend.so`                                     | XNNPACK CPU backend (required for most quantized models)      |
+| `coreml`     | ✅ — `CoreMLBackend.xcframework` force-loaded into the app                  | n/a (CoreML is iOS-only)                                                                      | Core ML backend (Apple Neural Engine / GPU acceleration)      |
+| `vulkan`     | n/a (Vulkan is Android-only)                                                | ✅ — separately-loaded `libvulkan_executorch_backend.so`                                      | Vulkan GPU backend                                            |
+
+Source files and native libraries are excluded from compilation when an extra 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 `extras`, 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: