feat: on-demand native lib download with opt-in feature splitting

The npm tarball ships without prebuilt native binaries — they are
downloaded from GitHub Releases at postinstall and extracted into
third-party/, where the existing CMake / podspec configurations pick them
up unchanged. Apps can opt out of features they don't need to skip both
the download and the native compilation:

    "react-native-executorch": {
      "extras": ["opencv", "phonemizer", "xnnpack", "coreml", "vulkan"]
    }

Defaults to all enabled. Each extra trims one or more artifacts and toggles
a corresponding RNE_ENABLE_* CMake / podspec flag, dropping its sources from
compilation and its libraries from the final link.

Per-platform behavior:
- opencv      Android + iOS (iOS provided via opencv-rne CocoaPod)
- phonemizer  Android + iOS
- xnnpack     iOS-only as a force-loaded XnnpackBackend.xcframework;
              baked into libexecutorch.so on Android
- coreml      iOS-only as a force-loaded CoreMLBackend.xcframework
- vulkan      Android-only as a separately-loaded
              libvulkan_executorch_backend.so

Vulkan ships as its own shared library (mirroring the QNN backend pattern)
so its load-time backend registration runs only when the user opts in. The
.so links only against vulkan_backend + vulkan_schema + executorch_core,
not the CPU kernel registries, so it does not cause duplicate kernel
registration when loaded alongside libexecutorch.so.

Author: msluszniak

.cspell-wordlist.txt

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

.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: