fix(deps): require worklets >=0.10.0 <0.13.0 and document it - #1449
Merged
Conversation
The peer was `^0.10.0`, which pins the library to React Native 0.83-0.86: worklets 0.10 requires RN 0.83+, so RN 0.81/0.82 and Expo SDK 54-56 could not install it at all. Widen it to `>=0.8.0 <0.11.0` - 0.8.0 is where `runOnRuntimeAsync` landed, the only API here newer than 0.5 - and close the one behavioural gap that opens up. Below 0.10.0 worklets serializes an ArrayBufferView by rebuilding it as `new Ctor(buffer)` on the target runtime, dropping byteOffset and length, so a window into a larger buffer (a slice of a recording, a pooled camera frame) arrives silently widened. Measured on a simulator, `new Uint8Array(buffer, 64, 16)` comes back with length 1024 on worklets 0.8.3 and 16 on 0.10.4. wrapAsync now tightens both directions first: any view that does not span its whole buffer is copied into one that does. An already-tight view - every buffer coming back from native - is passed through by reference, so the walk allocates nothing on the hot path. Also correct the documented range. The table claimed RN 0.81+ for 0.10.x with no mention of 0.86.
Supersedes the previous commit on this branch, which widened the peer down to 0.8.0 and copied every ArrayBufferView at the worklet boundary to make those versions behave. That bought only Expo SDK 54, React Native 0.81 and 0.82 - Expo 55 and 56 reach worklets 0.10 by asking for it, since the package version is not tied to the SDK - and it carried compat code for versions that are wrong rather than slow: below 0.10 an offset view arrives widened to its whole backing buffer. So keep 0.10 as the floor and fix the two real problems instead. The upper bound was `^0.10.0`, which excludes worklets 0.11 and 0.12. Those are the current releases, carry the same API with identical signatures, and typecheck clean here, so anyone installing `react-native-worklets` alongside this library met an unnecessary peer warning. And the requirement was never written down: the docs said React Native 0.81+/Expo SDK 54+ while the peer ruled both out, and the install command asks for `react-native-worklets` with no version at all. Getting Started now states the range, explains that worklets 0.10 is what sets the React Native 0.83 floor, and gives SDK 55/56 users the two versions to install (worklets and Reanimated move together). The compatibility table gains a React Native 0.86 column, drops 0.81/0.82 for 0.10.x, and a second table covers Expo SDKs. `__tests__/api/workletsVersionRange.test.ts` ties the range to the installed worklets, to the React Native floor it implies, and to the number in the docs - the pair that drifted in the first place.
msluszniak
changed the title
barhanc
reviewed
Sep 9, 2026
Comment on lines
+99
to
+102
| on SDK 56 — and `npx expo install` will pick that one. Ask for the versions | ||
| this library needs instead, together with the Reanimated release that expects | ||
| the same worklets (Reanimated pins it exactly, so bumping one without the other | ||
| gives you two incompatible native runtimes): |
Member
There was a problem hiding this comment.
Not sure we want to specifically mention Reanimated here, maybe just something along the lines that one needs to reconcile other package versions using worklets.
Member
Author
There was a problem hiding this comment.
updated in 1625be6, please check if this is what you meant.
Co-authored-by: Bartosz Hanc <bartosz.hanc02@gmail.com>
Applies review feedback: the requirement bullet states the range and nothing else, and the Expo caution no longer names Reanimated, since any package that uses worklets has to land on the same version.
barhanc
approved these changes
Sep 9, 2026
msluszniak
added a commit
that referenced
this pull request
Sep 9, 2026
0.10.0 is `lastVersion`, so the pages users land on still carried the pre-#1448/#1449/#1450 state: React Native 0.81+ / Expo SDK 54+, no worklets floor, no troubleshooting. - getting-started and the compatibility table take the #1449 changes verbatim, plus the minSdkVersion and troubleshooting pointers - native-libraries takes the monorepo and pnpm notes - a Troubleshooting page written against what 0.10.0 actually ships: the `use_frameworks!` header collision needs the Podfile `pre_install` workaround, the OpenCV conflict has no `opencvPod` escape hatch, and `minSdkVersion` defaults to 21 against API 26 `.so` files Also corrects the monorepo note on the current docs, which still said an app-level block is always ignored - the lookup now walks up from the installed package too.
8 tasks
msluszniak
added a commit
that referenced
this pull request
Sep 9, 2026
) ## Description Backports the three 0.10.0 setup fixes from `main` to `release/0.10`, plus the follow-up that fixes two defects in the third one. Cherry-picked with `-x`, no manual edits to any of them. | commit | PR | | --- | --- | | `12ce3bb` | #1448 fix(ios): narrow the podspec's public headers | | `c51f76a` | #1449 fix(deps): require worklets >=0.10.0 <0.13.0 and document it | | `a1ff6c9` | #1450 fix(build): fail with the cause when the setup is wrong | | `080e764` | #1452 fix(ios): keep the podspec's build attributes out of the OpenCV branch | All four are now on `main`; #1452 merged as `c8f44f6`. Only conflict was `docs/versioned_docs/version-0.10.0/**`: that snapshot exists on `main` only, since on this branch `docs/docs` **is** the 0.10 documentation. Those three hunks were dropped and the equivalent `docs/docs` changes came across in the same commits. `packages/react-native-executorch/package.json` keeps `0.10.0`; only the worklets peer range changed. ### Introduces a breaking change? - [ ] Yes - [x] No ### Type of change - [x] 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 `yarn workspace react-native-executorch test` passes, 3868 tests across 34 suites. The podspec, `android/build.gradle.kts`, `scripts/download-libs.js` and the new podspec test on this branch are byte-identical to `main`: ```bash git fetch origin main git diff origin/main HEAD -- packages/react-native-executorch/react-native-executorch.podspec \ packages/react-native-executorch/android/build.gradle.kts \ packages/react-native-executorch/scripts/download-libs.js \ packages/react-native-executorch/__tests__/api/podspecAttributes.test.ts ``` ### Related issues #1448, #1449, #1450, #1452 --------- Co-authored-by: Bartosz Hanc <bartosz.hanc02@gmail.com> Co-authored-by: Mateusz Słuszniak <msluszniak1@gmail.com>
msluszniak
added a commit
that referenced
this pull request
Sep 9, 2026
## Description Patch release **v0.10.1**. The fixes are already on `release/0.10` via #1451 (backports of #1448, #1449, #1450, #1452); this PR only bumps the version. - `packages/react-native-executorch/package.json`: `0.10.0` -> `0.10.1`. `nativeLibsVersion` stays `0.10.0`; the native artifacts release is unchanged. - `src/fetcher/telemetry.ts`: `LIB_VERSION` -> `0.10.1`, asserted equal to the package version by `__tests__/fetcher/telemetry.test.ts`. Satellites (`bare-resource-fetcher`, `expo-resource-fetcher`, `webrtc`) are untouched by the backports, so their versions stay at `0.10.0`. `models.ts` stays on `resolve/v0.10.0`; no model files moved. ### Introduces a breaking change? - [ ] Yes - [x] No ### Type of change - [x] Other (chores, tests, code style improvements etc.) ### Tested on - [ ] iOS - [ ] Android ### Testing instructions CI runs `yarn workspace react-native-executorch test`; the telemetry version assertion covers the bump. ### Related issues #1451 ### Checklist - [x] I have performed a self-review of my code - [x] My changes generate no new warnings
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
2 participants
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.
Description
The
react-native-workletspeer was^0.10.0and undocumented: the requirements page claimed React Native 0.81+ / Expo SDK 54+, which that peer rules out, and the install command asks for worklets with no version.peer becomes
>=0.10.0 <0.13.0.^0.10.0excluded worklets 0.11 and 0.12, the current releases, which carry the same API and typecheck clean here.0.10 stays the floor: it is the first release to serialize an
ArrayBufferViewnatively (reanimated #9475). Below it a view is rebuilt over its whole backing buffer, sonew Uint8Array(buffer, 64, 16)arrives withlength1024 instead of 16. Our public API takes views from user code, so that is silent corruption, not slowness.Getting Started states the range and what SDK 55/56 users must install, since those SDKs bundle an older worklets and Reanimated pins it exactly:
Cost: Expo SDK 54, React Native 0.81 and 0.82 drop out. Expo 55 and 56 are inside worklets 0.10's range once asked for explicitly.
Introduces a breaking change?
Type of change
Tested on
Testing instructions
0.81 - 0.850.83 - 0.860.83 - 0.87__tests__/api/workletsVersionRange.test.tsties the range to the installed worklets, to the React Native floor it implies, and to the number in the docs, which is the pair that drifted.Related issues
Follow-up to the compatibility question raised alongside #1448.
Checklist
Additional notes
The first commit took the opposite approach (peer down to 0.8.0 plus a copy at the worklet boundary); the second supersedes it, so review the net diff.
0.8.x/0.9.xon React Native 0.86 are marked untested rather than guessed. Flip those cells if you know.