React Native Reanimated: what the 4.x rewrite means for your app

The problem Reanimated solves that Animated does not

React Native ships an Animated API, and for simple fades and slides it is adequate. The limit shows up when a gesture drives the animation. In the stock API, the code that decides where a dragged card goes runs on the JavaScript thread, so any work already queued there (a network response, a list render) delays the frame. The result is a card that lags behind the finger.

Reanimated reimplements that API so the animation logic itself runs on a separate thread. The README describes the repository as containing two packages: React Native Reanimated, "a library for creating smooth animations and interactions in React Native", and React Native Worklets, "a library that enables multi-threaded JavaScript execution in React Native applications". The second package is the mechanism behind the first. Reanimated is for teams building gesture-driven interfaces, drag-and-drop, swipeable rows, animated charts, where a dropped frame is visible to the user rather than merely measurable.

How Worklets separates the animation thread from the JS thread

The architecture is a two-package split, and the repository layout makes it explicit: packages/react-native-reanimated and packages/react-native-worklets sit side by side, with a compatibility-check workflow in CI that verifies the two work together. Functions marked for off-thread execution are the unit of work. The Worklets package owns the runtime that executes them; Reanimated builds its animation and gesture APIs on top of that runtime.

The practical consequence is that Reanimated 4.x is not a self-contained dependency. Installing it pulls in a second package whose version has to line up, and the repository carries a dedicated CI job for that pairing. The repository also ships a Babel plugin under packages/react-native-worklets/plugin, and a second plugin variant under packages/react-native-worklets/plugin-oxc, both declared as workspaces. If your build pipeline does not run that plugin, the worklet transformation does not happen and the off-thread execution the library promises does not occur.

Where the documentation is thin is rollback. The README does not describe how to revert a 4.x installation to 3.x, and it does not document a codemod. The only guidance it gives for teams on the old architecture is to "consider adopting the New Architecture or stay with latest 3.x release". That is a fork in the road, not a migration path.

Installing Reanimated 4.x and animating a first value

The README does not inline install commands. It points to two documentation pages: the getting-started installation instructions for Reanimated and the equivalent page for Worklets. What the README does state is that the packages are published to npm, that the monorepo is managed with yarn 4.13.0, and that the example app lives under apps/common-app with its own README. Treat the documentation pages as the authoritative source for the exact command, because the package names and peer requirements there are more current than anything quoted second-hand.

The repository does give one concrete starting point that does not require a real app: the source code for the example app is under the apps/common-app directory, and the README says that if you want to play with the API without trying it on a real app you can run the example project, with installation instructions in the Example README at apps/fabric-example/README.md. That is the path to follow before wiring the library into your own project.

Before any of that works, the worklet plugin has to be registered in the build configuration. The plugin ships from the Worklets package, and the repository maintains a second variant for the oxc toolchain, so the correct entry depends on which transformer your project uses. The Reanimated documentation gives the exact plugin path for each setup; the README itself does not.

The API shape itself is not reproduced in the README, so the first real use is best taken from the documentation page the README links to. What the repository does confirm is the split: two packages, two installation pages, one plugin that has to run for the off-thread execution to happen at all.

The New Architecture requirement is not optional

The compatibility section is the most consequential paragraph in the README. Reanimated 4.x and Worklets "support only the New React Native architecture and three latest React Native versions". Both halves of that sentence are hard limits.

The architecture half means an app on the old architecture cannot use 4.x at all. The README's own advice is to adopt the New Architecture or stay on 3.x. For a team midway through that migration, this turns an animation library upgrade into a platform migration, and the two cannot be sequenced independently.

The version half means the support window moves. If your React Native version falls out of the three most recent, you are outside the supported set even if nothing in your code changed. That is a recurring maintenance cost, not a one-time upgrade. The repository runs nightly CI jobs against React Native nightly builds, Expo DevClient builds, TypeScript compatibility and the Windows hosted app, which indicates the surface area the maintainers track. It also indicates how many places a break can originate.

The last push to the repository was on 2026-09-21, and the most recent Reanimated release listed is 4.7.0 from 2026-09-18. The Worklets package has its own release stream, with 0.13.0 published on 2026-09-21 and 0.12.2 on 2026-09-08.

When Reanimated is the wrong dependency

If your animations are simple, Reanimated is more machinery than the job needs. The stock Animated API has no plugin step, no second package, and no architecture requirement. A screen with a fade-in and a button press scale does not benefit from moving work off the JS thread, because there is no contention to avoid.

The second case is testing. Reanimated and Worklets are native-backed modules, and Jest does not run native code. Search interest in mocking the library is high enough that it appears repeatedly in the queries people type, and the README says nothing about test configuration. The documentation pages are where that setup lives, and if your team has a large existing Jest suite, the mock configuration is work you inherit with the dependency.

The third case is a project that cannot move to the New Architecture on its own schedule. If that migration is blocked by a third-party native module you do not control, Reanimated 4.x is simply unavailable to you, and the README's answer is to stay on 3.x.

How this differs from the Animated API and from gesture libraries

The difference from Animated is not a feature list, it is where the code runs. Animated executes its animation logic on the JavaScript thread; Reanimated moves that logic to a separate thread through the Worklets runtime. The API surface is deliberately similar, which is why the README can call it a reimplementation rather than a new paradigm. The cost of that similarity is that the two are not interchangeable at the import level, and a codebase using Animated does not get the threading benefit by changing an import path alone.

A more interesting comparison is with gesture handling. Reanimated and Worklets are the execution layer, not the input layer. A gesture library detects the touch and reports it; Reanimated is what lets the response to that touch run off the JS thread. Teams sometimes evaluate them as alternatives when they are complementary, and the repository's topic list, which includes both animation and gesture, reflects that the two concerns sit in the same neighbourhood without being the same thing.

Licence, maintenance and what an upgrade actually costs

Both Reanimated and Worklets are licensed under the MIT License, per the README and the LICENSE file at the repository root. MIT permits commercial use and modification. It is a permissive licence with no copyleft obligation and no requirement to publish your changes. That is the whole of what the README states; the licence text itself is the authority on terms.

Maintenance is active by any measure the repository offers. The last push was on 2026-09-21, the same day as the Worklets 0.13.0 release, and Reanimated 4.7.0 landed three days earlier. The repository is not archived. The CI configuration runs nightly checks across React Native nightly, Expo DevClient, TypeScript compatibility, Windows, and a dedicated Reanimated plus Worklets compatibility job. That last one is the honest signal about upgrade cost: the two packages version independently, so an upgrade is a pairing decision, not a single version bump.

The practical cost is the support window. Because 4.x tracks the three latest React Native versions, a team that upgrades React Native on a slow cadence will periodically find itself outside the supported matrix and have to move both React Native and Reanimated together. Budget for that as a recurring item rather than a one-time migration.

Editorial conclusion

Adopt Reanimated 4.x if your app already runs the New React Native architecture and you are on one of the three latest React Native versions, since that is the only configuration the repository says it supports. Stay on the latest 3.x release if you are still on the old architecture, and skip it entirely if you need a single package with no native build step. Before committing, verify that the Reanimated and Worklets versions you install are compatible with each other, and check your test setup, because Jest needs its own mock configuration for these modules.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. software-mansion/react-native-reanimated on GitHub