Short version: if your app is heading to React Native 0.89, move react-native-reanimated to 4.8.0 and react-native-worklets to 0.14.0 together, and do it before (or with) the React Native bump. Reanimated 4.8 supports React Native 0.87 to 0.89 only, so apps still on 0.86 cannot take it. And if your package.json turns on USE_LEGACY_LAYOUT_ANIMATIONS_PROXY, the native build now stops with an error unless you also turn ENABLE_SHARED_ELEMENT_TRANSITIONS off, because 4.8.0 enables shared element transitions by default.
This is a source diff: we ran npm pack on react-native-reanimated 4.7.2 (17 Nov 2026) and 4.8.0 (19 Nov 2026), react-native-worklets 0.13.1 and 0.14.0 (19 Nov 2026), and react-native 0.88.1 and 0.89.0-rc.2, then compared the android/, apple/, Common/ folders, the podspecs and the Gradle files.
Why we did this: our React Native banking apps and TV apps animate with Reanimated, and the 0.89 upgrade is next on their list. Reanimated is the library that most often blocks a React Native bump, so we check it first.
The version table
Both packages ship a compatibility.json. Here is what 4.8.0’s copy says, matched with the peerDependencies in each package.json:
| Reanimated | React Native | Worklets |
|---|---|---|
| 4.8.x | 0.87, 0.88, 0.89 | 0.14.x |
| 4.7.x | 0.86, 0.87, 0.88 | 0.13.x |
| 4.6.x | 0.83 to 0.87 | 0.12.x |
Worklets follows the same window: 0.14.x declares "react-native": "0.87 - 0.89", 0.13.x declares "0.86 - 0.88".
Two things follow from that table:
- On React Native 0.86 you stop at Reanimated 4.7.2. Upgrade React Native to 0.87 or 0.88 first.
- On 0.87 or 0.88 you can take Reanimated 4.8 now, before you touch React Native. That splits the risky upgrade in two: animations first, React Native 0.89 later. This is the order we use.

Move Worklets and Reanimated in the same commit, then React Native on its own.
Reanimated’s CocoaPods script and Gradle build both run validate-react-native-version.js and validate-worklets-build.js (which calls validate-worklets-version.js), so a mismatch fails at pod install or Gradle sync rather than at runtime. The React Native 0.89 template itself is covered in our 0.89 release candidate post.
The flag that flipped: shared element transitions
The one change that can break a build without any code change on your side is in src/featureFlags/staticFlags.json, the file both the Podfile helper and android/build.gradle.kts read for default static feature flags:

ENABLE_SHARED_ELEMENT_TRANSITIONS is false in 4.7.2 and true in 4.8.0.
Both build scripts merge those defaults with the reanimated.staticFeatureFlags object in your app’s package.json, then check for conflicts. That check already existed in 4.7.2, but with shared element transitions off by default it never fired for apps that only set the legacy proxy. In 4.8.0 the error text says it plainly: “you need to explicitly disable ENABLE_SHARED_ELEMENT_TRANSITIONS feature flag (enabled by default)”.
So an app that kept the old layout animation proxy needs this in package.json:
{
"reanimated": {
"staticFeatureFlags": {
"USE_LEGACY_LAYOUT_ANIMATIONS_PROXY": true,
"ENABLE_SHARED_ELEMENT_TRANSITIONS": false
}
}
}
If you never set USE_LEGACY_LAYOUT_ANIMATIONS_PROXY, nothing fails, but shared element transitions are now compiled in. The 4.8.0 sources add the code behind it: SharedTransitionGeometry, SharedTransitionValuesFactory and PropsDiffer in Common/cpp/reanimated/LayoutAnimations, plus REASharedTransitionOverlays.mm on iOS. If you do not use the feature and want 4.7 behaviour, set the flag to false and test your screen transitions both ways.
A 30-line check for the upgrade
We wrote a small Node script that reads an app’s package.json and reports the three things above: the React Native and Reanimated pairing, the Worklets pairing, and the flag conflict. Here it is on a fixture app that moved React Native and Reanimated but forgot Worklets and still sets the legacy proxy:

Real output from Node 22 on our test machine. Two problems, both caught before pod install.
const table = { // from compatibility.json in reanimated 4.8.0
'4.8': { rn: ['0.87', '0.88', '0.89'], wl: '0.14' },
'4.7': { rn: ['0.86', '0.87', '0.88'], wl: '0.13' },
};
const flags = (app.reanimated || {}).staticFeatureFlags || {};
const set = flags.ENABLE_SHARED_ELEMENT_TRANSITIONS;
const legacy = flags.USE_LEGACY_LAYOUT_ANIMATIONS_PROXY === true;
const setOn = rea === '4.8' ? set !== false : set === true;
if (legacy && setOn) out.push('BUILD FAILS: legacy proxy + SET both on');
The part of the script that matters; the rest reads versions from dependencies.
iOS: what changed in the pods
RN_ALLOW_FRAMEWORKS=1added toGCC_PREPROCESSOR_DEFINITIONS(RNReanimated.podspec,RNWorklets.podspec,Package.swift): Silences React Native 0.89’s new C++ stable API “for frameworks” warning for these pods. Nothing to do.- Includes go through
__has_include(<React/View.h>)and similar, with the old paths as fallback (newCommon/cpp/*/Compat/ReactNative*.hheaders): On 0.89 the library uses React Native’s new umbrella headers; on 0.87 and 0.88 it falls back to the old ones. - Worklets iOS minimum now comes from React Native’s
min_ios_version_supportedinstead of a hard-coded13.4; tvOS likewise instead of9.0(RNWorklets.podspec): That helper returns15.1in React Native 0.89.0-rc.2. Your app was already at 15.1 or higher if it builds React Native. - New
PrivacyInfo.xcprivacybundled asRNWorklets_privacy(apple/PrivacyInfo.xcprivacy): DeclaresNSPrivacyAccessedAPICategorySystemBootTimewith reason35F9.1, no tracking, no collected data. It merges into your app’s privacy report; check the report before the next App Store upload. - WebSocket delegate added to the Worklets networking backend (
apple/worklets/apple/Networking/WorkletsWebSocketDelegate.mm): Only relevant if you use networking from a worklet runtime.
The umbrella headers are the part to understand. React Native 0.89.0-rc.2 ships 17 React/*.h umbrella headers in ReactCommon (0.88.1 ships 6), and a new guard: when an app opts in with RN_STRICT_API=1, including a fine-grained internal header directly produces a warning or an error. Reanimated 4.8 and Worklets 0.14 are already written for that. Older versions are not, which is one more reason not to pair Reanimated 4.7 with 0.89 even if you force the install.
Android: what changed in Gradle and CMake
android { }replaced byextensions.configure<LibraryExtension> { }(android/build.gradle.kts(both packages)): Typed AGP DSL access, the style newer Android Gradle Plugin versions expect. No change in your app.ndkPathandndkVersionread through a helper that accepts any string type and ignores empty values (android/build.gradle.kts): If you setndkVersionin the root project from a Kotlin DSL file, it is now picked up reliably.- Precompiled header plus ccache support (new
android/cmake/pch-ccache.cmake): Lets ccache reuse the native compile across checkouts at different paths (git worktrees). Useful in CI with ccache on; nothing to change otherwise. -Xwarning-level=DEPRECATION:errorand-Werror=deprecated-declarations(Gradle and podspecs): Only for Reanimated’s own example app. Your build does not get stricter.
What disappeared: the 0.86 code path
The cut-off is visible in the C++. In 4.7.2, ReanimatedModuleProxy.cpp carried a #if REACT_NATIVE_VERSION_MINOR >= 87 branch that worked around a stale event target during unmount on 0.86 (fixed in React Native 0.87 by facebook/react-native#56763). In 4.8.0 that branch is gone and the 0.87 code is the only path. That is why the peer range starts at 0.87, and why forcing 4.8 onto a 0.86 app with --legacy-peer-deps is a bad idea.
Across both packages, 169 existing native and build files differ, and about 40 are new. Most of the rest is new CSS animation support in Common/cpp/reanimated/CSS (platform colors, gradients, relative values) and runtime bookkeeping in Worklets (RuntimeIdentity, a new Registries folder). None of it needs code changes in an app.
What to check on your own app
- Read your
react-nativeversion. On 0.86, upgrade React Native to 0.88 first. - Bump
react-native-reanimatedto 4.8.0 andreact-native-workletsto 0.14.0 in one commit. - Search
package.jsonforstaticFeatureFlags. IfUSE_LEGACY_LAYOUT_ANIMATIONS_PROXYis true, add"ENABLE_SHARED_ELEMENT_TRANSITIONS": false. - Run
pod installand a Gradle sync; both validate the versions. - On iOS, open the generated privacy report of an archive and check the new Worklets entry.
- Test layout animations and screen transitions on both platforms, then move to React Native 0.89.
Sources: the 4.7.2 to 4.8.0 compare view, the Reanimated compatibility table and the npm packages named above.



