[RNE Rewrite] docs: rewrite documentation by barhanc · Pull Request #1388 · software-mansion/react-native-executorch

barhanc · 2026-08-27T12:00:13Z

Description

Comprehensive rewrite of documentation across Natural Language, Speech, and Computer Vision task extensions, alongside a modern overhaul of the root README.md reflecting the v0.10 architecture.

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

Build and view the documentation
```
cd docs
yarn build && yarn start
```
Build and test the showcase app at ~~https://github.com/barhanc/react-native-executorch-gallery~~ https://github.com/software-mansion-labs/react-native-executorch-gallery

Screenshots

Related issues

Closes #1163 #1288

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

barhanc · 2026-08-31T15:46:08Z

@msluszniak This is not yet fully ready, as I need to record all the videos for task docs and implement the vision camera demo, but the documentation content itself is ready to review. Two pages that require special attention are:

docs/docs/01-fundamentals/02-downloading-models.md
docs/docs/03-core-and-advanced/08-native-libraries.md

as these are mostly concerned with fetcher and the binaries split. The migration doc will need to be written once we merge the rewrite branch into main and resolve the API migration (after that we will have to also update the code snippets to use proper entry points but that's automatic work). The gallery repo also needs to be transfered to swm-labs and we are missing benchmarks.

msluszniak · 2026-08-31T15:51:05Z

@msluszniak This is not yet fully ready, as I need to record all the videos for task docs and implement the vision camera demo, but the documentation content itself is ready to review. Two pages that require special attention are:

docs/docs/01-fundamentals/02-downloading-models.md

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

as these are mostly concerned with fetcher and the binaries split. The migration doc will need to be written once we merge the rewrite branch into main and resolve the API migration (after that we will have to also update the code snippets to use proper entry points but that's automatic work). The gallery repo also needs to be transfered to swm-labs and we are missing benchmarks.

Understood. I'll scan through all the documentation with special attention to these two. Do we have an idea when specifically we want to merge rne-rewrite to main, after merging this PR?

barhanc · 2026-08-31T15:53:59Z

I'd say this should be the last PR merged into rne-rewrite before merging rne-rewrite into main, so we should wait with this one until everything else is ready-to-go, merge this and then merge rewrite into main.

msluszniak

First batch of suggestions, based on fundamentals and extensions sections. Now moving to core, readmes etc.

msluszniak · 2026-09-02T16:44:11Z

Docs build fails on ca9e1b0b: two broken links in docs/docs/02-extensions/speech/03-speech-to-text.md:101 point at 06-api-reference/type-aliases/WhisperStreamUpdate.md, which typedoc never generates, since stream() returns an inline anonymous { committed; nonCommitted } rather than an exported type alias (whisperSpeechToText.ts:162).

Dropping those two links (or exporting WhisperStreamUpdate) makes yarn build pass clean.

…ns & core overview - Rewrite getting-started with two-layer architecture intro, ExecuTorch as PyTorch Core project - Add 'Selecting native libraries' subsection under Installation - Move native-libraries to core-and-advanced, rewrite for readability with full feature table - Remove architecture.md and loading-models.md from fundamentals - Move migrating-from-v0-9.md to #2 in fundamentals - Add generated-index cards for Extensions and Core & Advanced sections - Add extensions overview pages for computer-vision, natural-language, speech - Fix broken anchors and links throughout

…tegories

…s, errors, worklets) - Rewrite Models & Tensors around the explicit fn(src, dst) memory model, through-chaining, lifecycle, and thread safety - Add Schema Validation: exported vs allowed specs, symbolic dims, domains vs runtime constraints, primitives, multi-method models, get_model_schema - Add Operations & Utilities (renamed from Tensor Operations): native math/cv/speech ops plus nlp/llm and numeric utilities - Add Error Handling: the code set, isRnExecuTorchError narrowing, throwing - Add Worklets & Threading: the three execution contexts, wrapAsync, the dual-API pattern - Reorder sidebar so Error Handling precedes Worklets & Threading - Cross-link every symbol to the API reference; minor getting-started polish Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Cover integrating a custom .pte both into a built-in pipeline (inspectModel, discovering the contract, reconciling) and into a custom pipeline you build on the primitives. Delegate actual export to the ExecuTorch docs. Document the get_model_schema companion for dynamic shapes, with the payload's JSON Schema embedded in a collapsible for reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Add a Fundamentals "Downloading Models" page: the models registry, automatic download/caching in hooks (useResourceDownload, ResourceOptions), the imperative download API (DownloadOptions: progress, abort, forceDownload), and caching behavior; renumber the migration guide to 03 - Document the new createResourceScope primitive in the Models & Tensors lifecycle section (failure-safe construction) and reference it from the custom-pipeline example in Exporting Custom Models Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@returns

- Add @typeParam/@param/@returns to ResourceScope.track in lifetime.ts so the generated reference documents the generic - Link createResourceScope, ResourceScope, and NativeResource from the Models & Tensors lifecycle section and API-reference list (--no-verify: the pre-commit `types` hook fails on pre-existing @types/jest errors in upstream __tests__; unrelated to this jsdoc/docs change) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Re-add the Other > Compatibility page (from main) that the rewrite restructure dropped, and link it from Getting Started with a relative doc link instead of a raw URL - Drop the two resource-fetcher compatibility tables, since those packages no longer exist in this version (the fetcher is built into react-native-executorch) - Trim the extensions category description to one sentence Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… multi-model entries

…OCR docs

…bed methods

…ose guide

…guide

…efix

…x in STT guide

… options

… guide

msluszniak · 2026-09-02T16:48:45Z

List of supported backends is not up to date.

Yeah this whole file should be rewritten, but I just don't really know what to put there regarding native libraries download, e.g. the building from source part doesn't really fit.

Yeah building from source is on our side so probably we shouldn't mention it.

msluszniak

Symbol level accuracy is good: every imported name, models.* registry path, namespace member and the error code table check out against source. Points below.

One finding with no diff anchor: docs-build-check.yml only triggers on PRs to main, so the docs build never ran on this PR. That matters because it adds ~740 relative links into the typedoc generated 06-api-reference/, which nothing has verified, and onBrokenLinks is throw. Worth adding rne-rewrite to that workflow here.

msluszniak · 2026-09-02T17:17:59Z

+
+  // Hook state:
+  // classifier.isReady          — true once model is downloaded and loaded in memory
+  // classifier.downloadProgress — 0.0 to 1.0 download progress


downloadProgress is 0 to 100, not 0.0 to 1.0: useResourceDownload sets progress * 100 and the hooks forward it verbatim. The same wrong comment is in 14 other extension guides. Note download()'s onProgress really is 0 to 1, so the two APIs differ and only this one is wrong.

msluszniak · 2026-09-02T17:17:59Z

+        description:
+          'Lower-level APIs for direct ExecuTorch model execution, tensor operations, and custom pipelines.',
+      },
+      items: [{ type: 'autogenerated', dirName: '03-core-and-advanced' }],


07-other is never added here, so the new compatibility page gets no sidebar entry and is reachable only by direct URL. The old file had a commented-out Other category that was dropped rather than re-enabled.

msluszniak · 2026-09-02T17:17:59Z

+        <td><div className={styles.supported}>yes</div></td>
+      </tr>
+      <tr>
+        <td><div className={styles.version}>0.9.x</div></td>


No 0.10.x row, which is the version this PR documents, we want to keep this one or not really?

msluszniak · 2026-09-02T17:17:59Z

-This allows us to use binaries, such as exported models or tokenizers for LLMs.
+- **New Architecture** enabled
+- **React Native 0.81+** (or compatible Expo SDK using development builds)
+- **iOS 17.0+** / **Android 13+ (API 33)**


Where does API 33 come from? android/build.gradle.kts defaults minSdk = 21 and RN 0.81's own floor is 24. iOS 17.0 checks out against the podspec. Also no minimum Expo SDK is given despite the line above.

msluszniak · 2026-09-02T17:18:00Z

-When using Expo, please note that you need to use a custom development build of your app, not the standard Expo Go app. This is because we rely on native modules, which Expo Go doesn’t support.
+For supported React Native versions, see the [Compatibility
+table](../07-other/01-compatibility.mdx).
 :::


The old getting started warned that iOS Release builds cannot target a simulator. That caveat is now nowhere in the docs and it is a recurring support question. Is this still an issue or not really anymore?

msluszniak · 2026-09-02T17:18:00Z

+const model = await wrapAsync(loadModel)('/path/to/model.pte');
+
+// Inside a worklet runtime, the synchronous call is fine
+const model = loadModel('/path/to/model.pte');


const model is declared twice in this block, so the snippet does not compile as pasted. The question is if we want our snippets to be compilable? If not necessary, then just skip this comment and resolve.

msluszniak · 2026-09-02T17:18:00Z

+
+## Throwing Errors in Custom Pipelines
+
+When writing custom pipelines or task helpers, use the [`RnExecuTorchError`](../06-api-reference/functions/RnExecuTorchError.md) factory function. Do **not** use `new RnExecuTorchError()`, as plain object factories can be safely passed across worklet boundaries:


The reason clause does not support the prohibition. Should be closer to: class instances lose their prototype across worklet boundaries, plain object factories survive.

msluszniak · 2026-09-02T17:18:00Z

+
+```typescript
+import { models, useLLMChatSession } from 'react-native-executorch';
+import type { ImageBuffer } from 'react-native-executorch/cv';


Subpath imports (react-native-executorch/cv, /llm) are used in snippets but never explained anywhere, and are silently mixed with namespace imports from the root. One sentence in Operations & Utilities would cover it.

msluszniak · 2026-09-02T17:18:00Z

-  "compilerOptions": {
-    "skipLibCheck": true
-  },
+  "compilerOptions": { "skipLibCheck": true },


Gratuitous reformat that prettier may revert. The validation block added below is a good change though.

msluszniak · 2026-09-02T17:18:00Z

+# Linguist vendoring for accurate language statistics and cloc
+third-party/** linguist-vendored
+**/third-party/** linguist-vendored
+packages/react-native-executorch/third-party/** linguist-vendored


**/third-party/** already covers both other rules. Also still no trailing newline, and this is unrelated to a docs PR.

msluszniak · 2026-09-02T17:32:45Z

Also, I think that is the right moment to wire some maybe not-working but targeting main CI for validating and publishing documentation like we have on main.

barhanc self-assigned this Aug 27, 2026

barhanc added the documentation Improvements or additions to documentation label Aug 27, 2026

barhanc force-pushed the @bh/docs branch 2 times, most recently from e6ca40e to 0a92126 Compare August 27, 2026 14:59

barhanc changed the title ~~@bh/docs~~ [RNE Rewrite] docs: rewrite documentation Aug 31, 2026

barhanc marked this pull request as ready for review August 31, 2026 15:41

msluszniak self-requested a review August 31, 2026 15:44

This was linked to issues Aug 31, 2026

Docs - refactor & simplification #1163

Open

[RNE Rewrite] Streamline apps to show idiomatic usage of the library #1288

Open

barhanc force-pushed the @bh/docs branch 5 times, most recently from ebe7495 to 40be1d0 Compare September 2, 2026 00:15

msluszniak reviewed Sep 2, 2026

View reviewed changes

barhanc and others added 11 commits September 2, 2026 18:48

docs: sync media assets and clean up sidebar config

12ee8f8

docs: add legacy v0.9 docs directory

2672dc3

docs: add generated index cards for extensions and core & advanced ca…

e0e94a3

…tegories

docs: remove legacy docs

ee28c00

docs: link the compatibility table from Getting Started requirements

612c184

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

barhanc added 25 commits September 2, 2026 18:48

docs: update gallery task file links to (screens) path

e315b3b

chore(git): mark third-party code as linguist-vendored in .gitattributes

ed801a5

docs: integrate gallery showcase link into intro and streamline layout

c1a3f5d

docs: remove all horizontal rule separators from README

7e28a84

docs: add open Table of Contents with updated section links

d5a5f9e

docs: add Custom Pipelines to Supported Capabilities matrix

8efba4c

docs: use computer vision in introduction overview

6cbfe81

docs: use stable ExecuTorch documentation URL across guides

4449b04

docs: refine getting started guide options and examples

fef4d85

docs: use Notes header and Core ML (Apple) backend naming format

63ec438

docs: shorten variant links to See and standardize Size Range headers

6da98c4

docs: use See for single model variants and descriptive sub-names for…

c07bd85

… multi-model entries

docs: clarify speed vs voice quality trade-offs in TTS model table

c269df0

docs: add note about CRAFT deprecation and future EasyOCR package in …

bb6b56a

…OCR docs

docs: clarify PyTorch native C++ tokenizer engine

f511c4e

docs: better wording

bfcbd1f

docs: add missing links to models, math functions, color maps, and em…

f219284

…bed methods

docs: link YOLO26_POSE, BLAZEFACE, COCO_LANDMARKS, and landmarks in P…

c13bf4f

…ose guide

docs: ensure all landmark constants and names are linked

b93bc55

docs: link Quad, recognizeCharacters, and OcrDetection fields in OCR …

4f5fe18

…guide

docs: streamline STT workflows and direct method links without stt pr…

96a1940

…efix

docs: link streamInsert and transcribeStop directly without stt prefi…

1de87be

…x in STT guide

docs: streamline VAD workflows, remove vad prefix, and link methods &…

825c70e

… options

docs: streamline Gallery App callouts to link only screen files

dc5ab31

docs: remove unresolvable WhisperStreamUpdate links in speech-to-text…

57f7c92

… guide

msluszniak reviewed Sep 2, 2026

View reviewed changes

barhanc force-pushed the @bh/docs branch from 2db9811 to 57f7c92 Compare September 2, 2026 16:49

msluszniak reviewed Sep 2, 2026

View reviewed changes

docs: add side-by-side iOS and Android task showcase recordings

67b986f


		## Throwing Errors in Custom Pipelines

		When writing custom pipelines or task helpers, use the [`RnExecuTorchError`](../06-api-reference/functions/RnExecuTorchError.md) factory function. Do not use `new RnExecuTorchError()`, as plain object factories can be safely passed across worklet boundaries:

Uh oh!

Conversation

barhanc commented Aug 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!

barhanc commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

msluszniak commented Aug 31, 2026

Uh oh!

barhanc commented Aug 31, 2026

Uh oh!

msluszniak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

msluszniak commented Sep 2, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msluszniak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msluszniak Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msluszniak Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msluszniak Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msluszniak commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

barhanc commented Aug 27, 2026 •

edited

Loading

barhanc commented Aug 31, 2026 •

edited

Loading

msluszniak Sep 2, 2026 •

edited

Loading

msluszniak Sep 2, 2026 •

edited

Loading

msluszniak Sep 2, 2026 •

edited

Loading