Skip to content

Commit b0caf76

Browse files
authored
chore: created docs 0.9.x (#1184)
## Description Step 10/11 of the minor release process: snapshots the current docs into `docs/versioned_docs/version-0.9.x/` via `yarn docs:version 0.9.x`. Source-code references pinned to SHA `0e95b8934` (the commit `release/0.9` was cut from). Adds `0.9.x` to `docs/versions.json` and creates the matching `versioned_sidebars/version-0.9.x-sidebars.json`. Audited: zero `/blob/main/` refs survived the rewrite, zero broken cross-links across 480 versioned files. > [!IMPORTANT] > Merge AFTER v0.9.0 has been published to npm. The docs publish workflow ships the merged docs immediately, and we don't want users to see v0.9.x docs that point at unreleased code. ### Introduces a breaking change? - [ ] Yes - [x] No ### Type of change - [ ] Bug fix (change which fixes an issue) - [ ] New feature (change which adds functionality) - [x] Documentation update (improves or adds clarity to existing documentation) - [ ] Other (chores, tests, code style improvements etc.) ### Tested on - [ ] iOS - [ ] Android ### Testing instructions N/A — pure docs versioning snapshot, no runtime change. ### Screenshots ### Related issues ### Checklist - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [x] I have updated the documentation accordingly - [x] My changes generate no new warnings
1 parent 0e95b89 commit b0caf76

496 files changed

Lines changed: 36337 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: Getting Started
3+
slug: /fundamentals/getting-started
4+
keywords:
5+
[
6+
react native,
7+
react native ai,
8+
react native llm,
9+
react native qwen,
10+
react native llama,
11+
react native executorch,
12+
executorch,
13+
on-device ai,
14+
pytorch,
15+
mobile ai,
16+
]
17+
description: 'Get started with React Native ExecuTorch - a framework for running AI models on-device in your React Native applications.'
18+
---
19+
20+
import Tabs from '@theme/Tabs';
21+
import TabItem from '@theme/TabItem';
22+
23+
## What is ExecuTorch?
24+
25+
[ExecuTorch](https://executorch.ai) is a novel AI framework developed by Meta, designed to streamline deploying PyTorch models on a variety of devices, including mobile phones and microcontrollers. This framework enables exporting models into standalone binaries, allowing them to run locally without requiring API calls. ExecuTorch achieves state-of-the-art performance through optimizations and delegates such as Core ML and XNNPACK. It provides a seamless export process with robust debugging options, making it easier to resolve issues if they arise.
26+
27+
## React Native ExecuTorch
28+
29+
React Native ExecuTorch is our way of bringing ExecuTorch into the React Native world. Our API is built to be simple, declarative, and efficient. Additionally, we provide a set of pre-exported models for common use cases, so you don't have to worry about handling exports yourself. With just a few lines of JavaScript, you can run AI models (even LLMs 👀) right on your device—keeping user data private and saving on cloud costs.
30+
31+
## Compatibility
32+
33+
React Native Executorch supports only the [New React Native architecture](https://reactnative.dev/architecture/landing-page).
34+
35+
If your app still runs on the old architecture, please consider upgrading to the New Architecture.
36+
37+
For supported React Native and Expo versions, see the [Compatibility table](../07-other/01-compatibility.mdx).
38+
39+
## Installation
40+
41+
Installation takes two steps: install the core package, then install a resource fetcher adapter that matches your project type. If you want to implement your own model fetching logic instead, see [this document](../08-resource-fetcher/02-custom-adapter.md).
42+
43+
### 1. Install the core package
44+
45+
<Tabs groupId="package-manager">
46+
<TabItem value="npm" label="npm">
47+
48+
```bash
49+
npm install react-native-executorch
50+
```
51+
52+
</TabItem>
53+
<TabItem value="pnpm" label="pnpm">
54+
55+
```bash
56+
pnpm add react-native-executorch
57+
```
58+
59+
</TabItem>
60+
<TabItem value="yarn" label="yarn">
61+
62+
```bash
63+
yarn add react-native-executorch
64+
```
65+
66+
</TabItem>
67+
</Tabs>
68+
69+
### 2. Install a resource fetcher
70+
71+
Pick the adapter that matches your project. We recommend the Expo adapter when your app uses Expo; use the bare adapter for projects without Expo.
72+
73+
#### Expo projects
74+
75+
<Tabs groupId="package-manager">
76+
<TabItem value="npm" label="npm">
77+
78+
```bash
79+
npm install react-native-executorch-expo-resource-fetcher expo-file-system expo-asset
80+
```
81+
82+
</TabItem>
83+
<TabItem value="pnpm" label="pnpm">
84+
85+
```bash
86+
pnpm add react-native-executorch-expo-resource-fetcher expo-file-system expo-asset
87+
```
88+
89+
</TabItem>
90+
<TabItem value="yarn" label="yarn">
91+
92+
```bash
93+
yarn add react-native-executorch-expo-resource-fetcher expo-file-system expo-asset
94+
```
95+
96+
</TabItem>
97+
</Tabs>
98+
99+
#### Bare React Native projects
100+
101+
<Tabs groupId="package-manager">
102+
<TabItem value="npm" label="npm">
103+
104+
```bash
105+
npm install react-native-executorch-bare-resource-fetcher @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
106+
```
107+
108+
</TabItem>
109+
<TabItem value="pnpm" label="pnpm">
110+
111+
```bash
112+
pnpm add react-native-executorch-bare-resource-fetcher @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
113+
```
114+
115+
</TabItem>
116+
<TabItem value="yarn" label="yarn">
117+
118+
```bash
119+
yarn add react-native-executorch-bare-resource-fetcher @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
120+
```
121+
122+
</TabItem>
123+
</Tabs>
124+
125+
:::warning
126+
Before using any other API, you must call `initExecutorch` with a resource fetcher adapter at the entry point of your app:
127+
128+
```js
129+
import { initExecutorch } from 'react-native-executorch';
130+
import { ExpoResourceFetcher } from 'react-native-executorch-expo-resource-fetcher';
131+
// or BareResourceFetcher for bare react-native projects
132+
133+
initExecutorch({ resourceFetcher: ExpoResourceFetcher });
134+
```
135+
136+
Calling any library API without initializing first will throw a `ResourceFetcherAdapterNotInitialized` error.
137+
:::
138+
139+
Our library offers support for both bare React Native and Expo projects. Please follow the instructions from [Loading models section](./02-loading-models.md) to make sure you setup your project correctly. We encourage you to use Expo project if possible. If you are planning to migrate from bare React Native to Expo project, the link (https://docs.expo.dev/bare/installing-expo-modules/) offers a guidance on setting up Expo Modules in a bare React Native environment.
140+
141+
If you plan on using your models via require() instead of fetching them from a url, you also need to add following lines to your `metro.config.js`:
142+
143+
```json
144+
// metro.config.js
145+
...
146+
defaultConfig.resolver.assetExts.push('pte')
147+
defaultConfig.resolver.assetExts.push('bin')
148+
...
149+
```
150+
151+
This allows us to use binaries, such as exported models or tokenizers for LLMs.
152+
153+
:::warning
154+
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.
155+
:::
156+
157+
:::info
158+
Because we are using ExecuTorch under the hood, you won't be able to build iOS app for release with simulator selected as the target device. Make sure to test release builds on real devices.
159+
:::
160+
161+
Running the app with the library:
162+
163+
<Tabs groupId="package-manager">
164+
<TabItem value="npm" label="npm">
165+
166+
```bash
167+
npm run <ios|android> -- -d
168+
```
169+
170+
</TabItem>
171+
<TabItem value="pnpm" label="pnpm">
172+
173+
```bash
174+
pnpm <ios|android> -d
175+
```
176+
177+
</TabItem>
178+
<TabItem value="yarn" label="yarn">
179+
180+
```bash
181+
yarn <ios|android> -d
182+
```
183+
184+
</TabItem>
185+
</Tabs>
186+
187+
## Building from source
188+
189+
To build the library from source instead, clone the repository and initialize submodules:
190+
191+
```bash
192+
git clone -b release/0.9 https://github.com/software-mansion/react-native-executorch.git
193+
cd react-native-executorch
194+
195+
git submodule update --init --recursive packages/react-native-executorch/third-party/common
196+
197+
yarn
198+
```
199+
200+
## Supporting new models in React Native ExecuTorch
201+
202+
Adding new functionality to the library follows a consistent three-step integration pipeline:
203+
204+
1. **Model Serialization:** Export PyTorch model for a specific task (e.g. object detection) into the `*.pte` format, which is optimized for the ExecuTorch runtime.
205+
206+
2. **Native Implementation:** Develop a C++ execution layer that interfaces with the ExecuTorch runtime to handle inference. This layer also manages model-dependent logic, such as data pre-processing and post-processing.
207+
208+
3. **TS Bindings:** Finally, implement a TypeScript API that bridges the JavaScript environment to the native C++ logic, providing a clean, typed interface for the end user.
209+
210+
## Good reads
211+
212+
If you want to dive deeper into ExecuTorch or our previous work with the framework, we highly encourage you to check out the following resources:
213+
214+
- [ExecuTorch docs](https://pytorch.org/executorch/stable/index.html)
215+
- [React Native RAG](https://blog.swmansion.com/introducing-react-native-rag-fbb62efa4991)
216+
- [Offline Text Recognition on Mobile: How We Brought EasyOCR to React Native ExecuTorch](https://blog.swmansion.com/bringing-easyocr-to-react-native-executorch-2401c09c2d0c)
Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: Loading Models
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
There are three different methods available for loading model files, depending on their size and location.
9+
10+
## Prerequisites
11+
12+
In our library, you can use two different resource fetching mechanisms. One is implemented using Expo FileSystem, the other one uses external library. We encourage you to use implementation utilizing Expo if possible.
13+
14+
To use the Expo adapter, please add these libraries:
15+
16+
<Tabs groupId="package-manager">
17+
<TabItem value="npm" label="npm">
18+
19+
```bash
20+
npm install react-native-executorch-expo-resource-fetcher expo-file-system expo-asset
21+
```
22+
23+
</TabItem>
24+
<TabItem value="pnpm" label="pnpm">
25+
26+
```bash
27+
pnpm add react-native-executorch-expo-resource-fetcher expo-file-system expo-asset
28+
```
29+
30+
</TabItem>
31+
<TabItem value="yarn" label="yarn">
32+
33+
```bash
34+
yarn add react-native-executorch-expo-resource-fetcher expo-file-system expo-asset
35+
```
36+
37+
</TabItem>
38+
</Tabs>
39+
40+
and then add the following code in your React Native app:
41+
42+
```typescript
43+
import { initExecutorch } from 'react-native-executorch';
44+
import { ExpoResourceFetcher } from 'react-native-executorch-expo-resource-fetcher';
45+
46+
initExecutorch({
47+
resourceFetcher: ExpoResourceFetcher,
48+
});
49+
```
50+
51+
If you cannot use Expo in your project, proceed with the following steps:
52+
53+
<Tabs groupId="package-manager">
54+
<TabItem value="npm" label="npm">
55+
56+
```bash
57+
npm install react-native-executorch-bare-resource-fetcher @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
58+
```
59+
60+
</TabItem>
61+
<TabItem value="pnpm" label="pnpm">
62+
63+
```bash
64+
pnpm add react-native-executorch-bare-resource-fetcher @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
65+
```
66+
67+
</TabItem>
68+
<TabItem value="yarn" label="yarn">
69+
70+
```bash
71+
yarn add react-native-executorch-bare-resource-fetcher @dr.pogodin/react-native-fs @kesha-antonov/react-native-background-downloader
72+
```
73+
74+
</TabItem>
75+
</Tabs>
76+
77+
and
78+
79+
```typescript
80+
import { initExecutorch } from 'react-native-executorch';
81+
import { BareResourceFetcher } from 'react-native-executorch-bare-resource-fetcher';
82+
83+
initExecutorch({
84+
resourceFetcher: BareResourceFetcher,
85+
});
86+
```
87+
88+
## Loading
89+
90+
### Load from React Native assets folder (for files < 512MB)
91+
92+
```typescript
93+
useExecutorchModule({
94+
modelSource: require('../assets/lfm2_5.pte'),
95+
});
96+
```
97+
98+
### Load from remote URL
99+
100+
For files larger than 512MB or when you want to keep size of the app smaller, you can load the model from a remote URL (e.g. HuggingFace).
101+
102+
```typescript
103+
useExecutorchModule({
104+
modelSource: 'https://.../lfm2_5.pte',
105+
});
106+
```
107+
108+
### Load from local file system
109+
110+
If you prefer to delegate the process of obtaining and loading model and tokenizer files to the user, you can use the following method:
111+
112+
```typescript
113+
useExecutorchModule({
114+
modelSource: 'file:///var/mobile/.../lfm2_5.pte',
115+
});
116+
```
117+
118+
:::note
119+
The downloaded files are stored in documents directory of your application.
120+
:::
121+
122+
## Predefined Models
123+
124+
Our library offers out-of-the-box support for multiple models. To make things easier, we created aliases for our model exported to `pte` format. For full list of aliases, check out: [API Reference](../06-api-reference/index.md#models---classification)
125+
126+
## Example
127+
128+
The following code snippet demonstrates how to load model and tokenizer files using `useLLM` hook:
129+
130+
```typescript
131+
import { models, useLLM } from 'react-native-executorch';
132+
const llm = useLLM({ model: models.llm.lfm2_5_1_2b_instruct() });
133+
```

0 commit comments

Comments
 (0)