docs(react-native): async view model instance creation via useViewModelInstance({ async: true })#797
Draft
mfazekas wants to merge 3 commits into
Draft
Conversation
…elInstance({ async: true })
…odelInstance example
mfazekas
added a commit
to rive-app/rive-nitro-react-native
that referenced
this pull request
Jul 13, 2026
…: true }) (#331) Port of #304 (merged to `feat/rive-ios-experimental`) to `main`. `useViewModelInstance(source, { async: true })` creates the instance via the `*Async` runtime APIs off the JS thread and returns `{ instance, isLoading, error }`. The sync overloads are deprecated per-overload (they block the JS thread via deprecated runtime APIs); `async: true` becomes the default in the next major. Overload/deprecation resolution is pinned with tsd (`yarn typetest`, gated in the CI lint job). Native side: the `*Async` lookups now hop to the main thread (Android `riveMainScope`, iOS `Promise.onMain`) since the legacy runtime has no internal synchronization (the #297 race class), and Android's `getViewModelInstance()` returns a main-thread-maintained snapshot instead of traversing the controller off-thread, without blocking JS. Porting notes: 1. Experimental's `legacy/` sources map onto this branch's flat layout (`android/src/main`, `ios/`); the `new/`-backend and expo57 harness changes from #304 don't apply here. 2. `src/hooks/useViewModelInstance.ts` and the ported example files are taken from the experimental branch (re-run through main's prettier), which also brings a small pre-#304 improvement: `createInstanceByName` failures on the sync path now `console.warn` and resolve null instead of throwing raw native errors. 3. The new e2e harness drops the android-experimental skips (`RiveFileFactory.getBackend()` doesn't exist here) and adds the `arbtboards-models-instances.riv` fixture. Behavioral notes (worth a release-note callout): 1. Android `riveViewRef.getViewModelInstance()` is now eventually consistent off the main thread: it returns the last main-thread snapshot and schedules a refresh, instead of the previous unsynchronized live read (the #297 race). One-shot readers — including the deprecated sync `useViewModelInstance(riveViewRef)` — can observe `null` where the racy read happened to catch a late auto-bind; the `async: true` path polls and is unaffected. 2. `useRive().riveViewRef` now starts as `undefined` (view pending) instead of `null` (failed/detached), mirroring the `useRiveFile` convention, and its type widens to `RiveViewRef | null | undefined`. 3. On the sync hook, a `null` source now settles to a terminal `{ instance: null, isLoading: false }` instead of reporting undefined/loading forever. Docs: rive-app/rive-docs#797 (draft until this ships).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the async instance-creation API landing in rive-app/rive-nitro-react-native#331:
useViewModelInstance(source, { async: true })returning{ instance, isLoading, error }, with the synchronous overloads deprecated.Updates the data-binding and overview pages to teach
async: trueas the recommended form (all example snippets migrated), and adds a "Migrating to v0.5.0+" section to the migration guide coveringisLoading, the deprecation,useRive().riveViewRefstarting asundefined, and the terminal null-source behavior.Draft until the runtime release ships; the v0.5.0 heading assumes that's the next version number.
mintlify broken-linksreports the same 33 pre-existing issues as main, none in the touched files.