fix(build): fail with the cause when the setup is wrong

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

@@ -86,10 +86,12 @@ React Native ExecuTorch requires:
 - **New Architecture** enabled
 - **React Native 0.83+** or **Expo SDK 55+** with [Development Builds](https://docs.expo.dev/develop/development-builds/introduction/) (**Expo Go is not supported** due to custom C++ native libraries)
 - **`react-native-worklets` 0.10 or newer** (`>=0.10.0 <0.13.0`)
-- **iOS 17.0+** / **Android 13+**
+- **iOS 17.0+** / **Android 13+** (`minSdkVersion` >= 26)
 
 For supported React Native versions, see the [Compatibility
-table](../05-other/01-compatibility.mdx).
+table](../05-other/01-compatibility.mdx). If an install or a build fails, see
+[Troubleshooting](../05-other/02-troubleshooting.md) — most of it comes down to
+the package manager skipping the postinstall hook, or to `use_frameworks!`.
 :::
 
 :::caution Expo SDK 55 and 56

docs/docs/03-core-and-advanced/08-native-libraries.md

@@ -47,6 +47,22 @@ Add a `react-native-executorch` block to your `package.json`:
 
 The three lists are merged, so you can pair high-level `features` with specific `backends` or `libs`. Re-run your package manager install after editing.
 
+:::note Monorepos
+The block is read from the directory the install was run in, then from every
+`package.json` above the installed package. A hoisted workspace resolves to the
+**root** either way, so put the block there; an app that keeps its own
+`node_modules` (pnpm, nohoist) is found from its own `package.json`.
+`node_modules/react-native-executorch/rne-build-config.json` records what was
+actually resolved, and the install log names the manifest it read.
+:::
+
+:::caution pnpm
+pnpm 10 and later do not run dependency build scripts unless you allow them, so
+the download never happens and the native build fails later on a missing file.
+Run `pnpm approve-builds react-native-executorch` once. See
+[Troubleshooting](../05-other/02-troubleshooting.md).
+:::
+
 ### Backends
 
 Hardware backends provide optimized execution kernels for specific processors and platforms. See the [ExecuTorch Backends documentation](https://docs.pytorch.org/executorch/stable/backends-section.html) for details on lowering and delegate compilation:

docs/docs/05-other/02-troubleshooting.md

@@ -0,0 +1,166 @@
+---
+title: Troubleshooting
+slug: /other/troubleshooting
+description: 'Build and install failures caused by a project setup React Native ExecuTorch cannot control, and what to do about each.'
+keywords:
+  [react native executorch, troubleshooting, use_frameworks, pnpm, opencv, cocoapods, simulator]
+---
+
+Failures that come from how a project is set up rather than from the library
+itself. Each one is reproducible, so the symptom is quoted exactly — search
+this page for the error you got.
+
+## `Build input files cannot be found` after install
+
+```
+error: Build input files cannot be found:
+'.../XnnpackBackend.xcframework/ios-arm64-simulator/libXnnpackBackend.a'
+```
+
+The native artifacts are not in the npm tarball. They are downloaded by a
+**postinstall** hook, and your package manager skipped it:
+
+- **pnpm 10 and later block dependency build scripts by default** and print
+  `Ignored build scripts: react-native-executorch` during install.
+- `--ignore-scripts`, and `npm ci --ignore-scripts`, do the same.
+
+Nothing fails at that point — not even `pod install`, which does not check that
+a vendored framework exists — so the error only appears once Xcode goes looking
+for the file. Recent versions fail during `pod install` (and during the Android
+configure phase) with this fix in the message instead. Re-run the hook:
+
+```bash
+pnpm approve-builds react-native-executorch   # pnpm
+npm rebuild react-native-executorch           # npm
+node node_modules/react-native-executorch/scripts/download-libs.js
+```
+
+## `Multiple commands produce .../Headers/Types.h`
+
+An app built with `use_frameworks!` — directly, as Firebase requires, or through
+expo-build-properties' `"useFrameworks": "static"` — makes CocoaPods build the
+pod as a framework and flat-copy its public headers into one directory.
+Versions up to 0.10.0 published every header, and several share a basename, so
+the build fails while it is still being planned.
+
+Update the library. On 0.10.0 exactly, force the pod back to a static library:
+
+```ruby
+pre_install do |installer|
+  installer.pod_targets.each do |pod|
+    if pod.name == 'react-native-executorch'
+      def pod.build_type
+        Pod::BuildType.static_library
+      end
+    end
+  end
+end
+```
+
+Expo SDK 55 and later already do this for you: their autolinking downgrades
+every pod that vendors an `.xcframework` to a static library, which is why an
+Expo app usually never sees this. Setting `buildReactNativeFromSource: true`
+turns that off again.
+
+## `transitive dependencies that include statically linked binaries`
+
+```
+[!] The 'Pods-YourApp' target has transitive dependencies that include
+statically linked binaries: (.../opencv-rne/opencv2.xcframework)
+```
+
+`use_frameworks!` with no argument means **dynamic** linkage, which CocoaPods
+refuses to combine with a statically linked dependency. Ask for static
+frameworks instead:
+
+```ruby
+use_frameworks! :linkage => :static
+```
+
+## `frameworks with conflicting names: opencv2.xcframework`
+
+Another pod vendors OpenCV under the same framework name — `react-native-fast-opencv`
+(via `FastOpenCV-iOS`) is the common one — and CocoaPods installs only one
+framework called `opencv2`.
+
+Recent versions handle this for you: when `react-native-fast-opencv` is
+installed alongside this library, we depend on the OpenCV it vendors instead of
+our own, and compile against that copy's headers. `pod install` prints which one
+it chose. Nothing to configure, and both libraries work in the same app.
+
+To force the choice, name the pod that should provide OpenCV:
+
+```json
+{
+  "react-native-executorch": {
+    "opencvPod": "opencv-rne"
+  }
+}
+```
+
+`opencv-rne` is ours; any pod that vendors an `opencv2.xcframework` is accepted.
+We only use `opencv2/core.hpp` and `opencv2/imgproc.hpp`, so an OpenCV 4.x build
+serves. Forcing ours while another OpenCV is installed brings the conflict back,
+which is what the setting is for when you would rather drop the other library.
+
+If you do not use this library's vision tasks at all, drop its OpenCV instead:
+
+```json
+{
+  "react-native-executorch": {
+    "backends": ["xnnpack", "coreml", "mlx"],
+    "libs": ["phonemis"]
+  }
+}
+```
+
+Re-run your package manager's install afterwards. See
+[Native Libraries](../03-core-and-advanced/08-native-libraries.md) for what each
+entry covers — leaving `opencv` out disables every computer-vision task.
+
+## `None of the architectures in ARCHS (x86_64) are valid`
+
+The library ships `arm64` slices only, and the podspec excludes `x86_64` from
+simulator builds. **Intel Macs cannot build for the iOS simulator**, and neither
+can an Apple silicon Mac running Xcode under Rosetta, or an Intel macOS CI
+image. Use an Apple silicon machine, or a physical device.
+
+## `The platform of the target ... may not be compatible`
+
+```
+[!] The platform of the target `YourApp` (iOS 16.4) may not be compatible with
+`react-native-executorch (0.10.0)` which has a minimum requirement of iOS 17.0.
+```
+
+This is a **warning**, so `pod install` still succeeds and the failure surfaces
+later. The library needs iOS 17. In an Expo app, set it explicitly — the default
+is lower:
+
+```json
+[
+  "expo-build-properties",
+  { "ios": { "deploymentTarget": "17.0" } }
+]
+```
+
+## The `react-native-executorch` config block is ignored
+
+The postinstall hook reads the block from the directory where the install was
+invoked (`INIT_CWD`), then from every `package.json` above the installed
+package. In a hoisted monorepo both land on the **workspace root**, so a block
+in `apps/mobile/package.json` is never seen — put it in the root `package.json`
+instead. The install log names the manifest that won, and
+`node_modules/react-native-executorch/rne-build-config.json` records which flags
+were written.
+
+## An old Android device or emulator crashes on load
+
+Native code is shipped for `arm64-v8a` and `x86_64` only. A build that also
+produces `armeabi-v7a` or `x86` splits (React Native's default
+`reactNativeArchitectures` lists all four) will package those without the
+library's `.so`, and loading it fails at runtime on such a device. Restrict the
+app to the supported ABIs:
+
+```properties
+reactNativeArchitectures=arm64-v8a,x86_64
+```

docs/versioned_docs/version-0.10.0/01-fundamentals/01-getting-started.md

@@ -84,11 +84,30 @@ pnpm add react-native-executorch react-native-worklets react-native-blob-util
 React Native ExecuTorch requires:
 
 - **New Architecture** enabled
-- **React Native 0.81+** or **Expo SDK 54+** with [Development Builds](https://docs.expo.dev/develop/development-builds/introduction/) (**Expo Go is not supported** due to custom C++ native libraries)
-- **iOS 17.0+** / **Android 13+**
+- **React Native 0.83+** or **Expo SDK 55+** with [Development Builds](https://docs.expo.dev/develop/development-builds/introduction/) (**Expo Go is not supported** due to custom C++ native libraries)
+- **`react-native-worklets` 0.10 or newer** (`>=0.10.0 <0.13.0`)
+- **iOS 17.0+** / **Android 13+** (set the app's `minSdkVersion` to 26 or higher)
 
 For supported React Native versions, see the [Compatibility
-table](../05-other/01-compatibility.mdx).
+table](../05-other/01-compatibility.mdx). If an install or a build fails, see
+[Troubleshooting](../05-other/02-troubleshooting.md) — most of it comes down to
+the package manager skipping the postinstall hook, or to `use_frameworks!`.
+:::
+
+:::caution Expo SDK 55 and 56
+Both bundle a `react-native-worklets` older than 0.10 — 0.7.4 on SDK 55, 0.8.3
+on SDK 56 — and `npx expo install` will pick that one. Install the version this
+library needs instead:
+
+```bash
+npm install react-native-worklets@^0.10.0
+```
+
+Any other package in your app that uses worklets has to be moved to a release
+built against the same version; two of them asking for different worklets gives
+you two incompatible native runtimes. Our own example apps reconcile them this
+way. **Expo SDK 54 cannot be supported**: it is React Native 0.81, below what
+worklets 0.10 accepts.
 :::
 
 ### Selecting native libraries

docs/versioned_docs/version-0.10.0/03-core-and-advanced/08-native-libraries.md

@@ -47,6 +47,20 @@ Add a `react-native-executorch` block to your `package.json`:
 
 The three lists are merged, so you can pair high-level `features` with specific `backends` or `libs`. Re-run your package manager install after editing.
 
+:::note Monorepos
+The block is read from the directory the install was run in, which in a
+workspace is the **root** — a block in an app's own `package.json` is ignored.
+`node_modules/react-native-executorch/rne-build-config.json` records what was
+actually resolved.
+:::
+
+:::caution pnpm
+pnpm 10 and later do not run dependency build scripts unless you allow them, so
+the download never happens and the native build fails later on a missing file.
+Run `pnpm approve-builds react-native-executorch` once. See
+[Troubleshooting](../05-other/02-troubleshooting.md).
+:::
+
 ### Backends
 
 Hardware backends provide optimized execution kernels for specific processors and platforms. See the [ExecuTorch Backends documentation](https://docs.pytorch.org/executorch/stable/backends-section.html) for details on lowering and delegate compilation:

docs/versioned_docs/version-0.10.0/05-other/01-compatibility.mdx

@@ -17,7 +17,7 @@ React Native ExecuTorch supports only the [New Architecture](https://reactnative
     <thead>
       <tr>
         <th rowSpan={2}>React Native ExecuTorch</th>
-        <th colSpan={8}>React Native version</th>
+        <th colSpan={9}>React Native version</th>
       </tr>
       <tr>
         <th>0.78</th>
@@ -28,6 +28,7 @@ React Native ExecuTorch supports only the [New Architecture](https://reactnative
         <th>0.83</th>
         <th>0.84</th>
         <th>0.85</th>
+        <th>0.86</th>
       </tr>
     </thead>
     <tbody>
@@ -41,6 +42,7 @@ React Native ExecuTorch supports only the [New Architecture](https://reactnative
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
+        <td><div className={styles.partial}>untested&#8224;</div></td>
       </tr>
       <tr>
         <td><div className={styles.version}>0.9.x</div></td>
@@ -52,18 +54,94 @@ React Native ExecuTorch supports only the [New Architecture](https://reactnative
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
+        <td><div className={styles.partial}>untested&#8224;</div></td>
       </tr>
       <tr>
         <td><div className={styles.version}>0.10.x</div></td>
         <td><div className={styles.notSupported}>no</div></td>
         <td><div className={styles.notSupported}>no</div></td>
         <td><div className={styles.notSupported}>no</div></td>
+        <td><div className={styles.notSupported}>no*</div></td>
+        <td><div className={styles.notSupported}>no*</div></td>
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
         <td><div className={styles.supported}>yes</div></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+<div className={styles.footnote}>
+
+**\*** `react-native-executorch` 0.10 needs `react-native-worklets`
+`>=0.10.0 <0.13.0`, and worklets 0.10 is the first release to serialize an
+`ArrayBufferView` natively ([reanimated
+#9475](https://github.com/software-mansion/react-native-reanimated/pull/9475));
+older ones rebuild the view over its whole backing buffer, losing `byteOffset`
+and `length`. Worklets 0.10 in turn requires React Native 0.83+, which is what
+rules out 0.81 and 0.82.
+
+**†** Not verified. 0.8.x and 0.9.x were released before React Native 0.86 and
+are maintained on the `legacy` dist-tag only.
+
+</div>
+
+## Expo SDK
+
+`npx expo install` picks the `react-native-worklets` an SDK bundles, which is
+older than this library needs on SDK 55 and 56. Both work once you ask for the
+versions below explicitly — Reanimated pins worklets exactly, so it moves with
+it.
+
+<div className={styles.compatibility}>
+  <table>
+    <thead>
+      <tr>
+        <th>Expo SDK</th>
+        <th>React Native</th>
+        <th>Bundled worklets</th>
+        <th>react-native-executorch 0.10.x</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><div className={styles.version}>54</div></td>
+        <td>0.81</td>
+        <td>0.5.1</td>
+        <td><div className={styles.notSupported}>no</div></td>
+      </tr>
+      <tr>
+        <td><div className={styles.version}>55</div></td>
+        <td>0.83</td>
+        <td>0.7.4</td>
+        <td><div className={styles.partial}>needs explicit versions</div></td>
+      </tr>
+      <tr>
+        <td><div className={styles.version}>56</div></td>
+        <td>0.85</td>
+        <td>0.8.3</td>
+        <td><div className={styles.partial}>needs explicit versions</div></td>
+      </tr>
+      <tr>
+        <td><div className={styles.version}>57</div></td>
+        <td>0.86</td>
+        <td>0.10.1</td>
         <td><div className={styles.supported}>yes</div></td>
       </tr>
     </tbody>
   </table>
 </div>
+
+<div className={styles.footnote}>
+
+On SDK 55 and 56, install both:
+
+```bash
+npm install react-native-worklets@^0.10.0 react-native-reanimated@^4.5.0
+```
+
+SDK 54 is React Native 0.81, below what worklets 0.10 accepts, so no
+combination of versions works there.
+
+</div>