Reanimated 4 and Worklets: two published packages and one New Architecture requirement

The repository publishes two packages, and the animations library is only half of it

The top of the README splits the repository in two. `packages/react-native-reanimated` is a library for creating smooth animations and interactions in React Native. `packages/react-native-worklets` is a library that enables multi-threaded JavaScript execution in React Native applications. The repository description calls the whole thing React Native's Animated library reimplemented, which is fair for the first package and silent about the second.

That split has consequences at install time and at upgrade time. Worklets has its own documentation site, its own getting-started page and its own version line: the release list shows Reanimated 4.7.1 on 2026-10-02 and 4.7.0 on 2026-09-18, while Worklets most recently shipped 0.13.1 on 2026-10-28. Two packages, two version series, one repository. Anyone evaluating this project needs a position on both, not just on the animation API.

Version 4 refuses the old architecture, and the fallback offered is 3.x

The compatibility section is two short paragraphs and they are the most important ones in the file. Reanimated 4.x and Worklets support only the New React Native architecture and the three latest React Native versions. If your app still runs on the old architecture, the README asks you to adopt the New Architecture or stay with the latest 3.x release.

Both branches are work. Migrating the architecture is the larger of the two, and staying on 3.x means carrying an older major version indefinitely while the compatibility workflow keeps checking newer combinations. Note what is absent: the README contains no compatibility table, no list of which React Native versions count as the three latest, and no note about what breaks between them. A version decision made from this README alone is guesswork.

The README carries no install command, only two pointers to separate docs pages

Installation gets one paragraph, and it contains no code. You are sent to the installation instructions for Reanimated and to the installation instructions for Worklets, each on its own documentation page under docs.swmansion.com. No npm command, no Babel snippet, no flag to set appears anywhere in the repository README.

Two consequences follow. First, the setup is a two part procedure, not one, and the second part concerns the package that enables multi-threaded JavaScript rather than the animation helpers. Second, since the flags and versions live on external pages, they can change without a commit here. Pin your React Native version, read both pages, and treat the README as a map rather than a procedure.

The Babel plugin is its own workspace package, and an oxc variant sits next to it

The workspace list in `package.json` names thirteen entries, and three of them are tooling rather than runtime code: `packages/eslint-plugin-reanimated`, `packages/react-native-worklets/plugin`, and `packages/react-native-worklets/plugin-oxc`. The plugin is therefore a package in its own right.

The oxc variant is the detail worth flagging. Alongside it the root of the repository carries `.oxfmtrc.json` and `.oxlintrc.json`, and the formatting scripts invoke `oxfmt` rather than a Prettier binary, while Markdown goes through remark with three separate rc files for different document types. So the repository maintains a plugin and an oxc variant of it and has partly moved its own lint and format stack. The README does not say which of the two a given project should configure, which means picking wrong is a build-time surprise rather than a documented choice.

Nightly CI, not the README, is where the compatibility matrix is enforced

The nightly section lists many build checks. Among the linked workflows are a main branch build, a Reanimated and Worklets compatibility check, a Reanimated compatibility check, a React Native nightly build check, an Expo dev client build check, a TypeScript compatibility test, a Windows hosted app build check, a use-frameworks build check, a URL validation run, runtime tests and a runtime test run under sanitizers. Two nightly npm publish badges cover Reanimated and Worklets separately.

Read that as the project's answer to questions the README leaves open. A Reanimated and Worklets version skew is caught by a dedicated workflow rather than by your build. Expo development clients, Windows and the `use_frameworks` CocoaPods setting are all exercised continuously. The flip side is that nightly publish workflows mean nightly-tagged packages exist on the registry, so an install that resolves to a nightly tag is a support question with no documentation behind it.

The two packages version independently, so 'latest' is two different numbers

Reanimated 4.7.0 shipped on 2026-09-18, Reanimated 4.7.1 on 2026-10-02 and Worklets 0.13.1 on 2026-10-28, with the repository's last push on 2026-11-02. That is a patch release two weeks after 4.7.0 and a Worklets release a few weeks later.

Because the version series are independent, `latest` resolves to two unrelated numbers and there is no single version string for the project as a whole. The root `package.json` makes that concrete: it is named `react-native-reanimated-monorepo`, marked private, and pinned at version `0.0.0`, so reading the repository root tells you nothing about the library you depend on. The repository's compatibility check workflow is its answer to a mismatched pair.

Five example apps, one showcase, and no statement of supported platforms

The examples section points at `apps/common-app` as the source for the showcase app, then tells you that if you want to try the API without a real application you can run the example project and check `apps/fabric-example/README.md` for installation instructions. The workspace list carries more: `apps/macos-example`, `apps/tvos-example`, `apps/web-example` and `apps/next-example`.

A web example and a Next.js example sit next to a Fabric example, a macOS example and a tvOS example, which tells you the library is exercised well beyond phones. It does not tell you which platforms are supported, because the README never says so. The examples show where the code is demonstrated; they are evidence of effort, not a support statement. If your target is not in that list, the question belongs to the Discord or the documentation, not to this file.

Editorial conclusion

Adopt Reanimated 4 with Worklets when your app already runs on the New React Native architecture and you are shipping on one of the three most recent React Native versions. Do not upgrade from 3.x into 4.x while the old architecture is still in place, because the README's own guidance in that case is to stay on the latest 3.x release, which is a second upgrade with its own costs. Before you start, read the installation page for Reanimated and the separate one for Worklets, since the README contains no install command and the two procedures are documented apart. Then confirm your exact Reanimated and Worklets versions against the compatibility workflow rather than assuming the newest tag of one matches the newest tag of the other. The last push was on 2026-11-02, Reanimated 4.7.1 shipped on 2026-10-02, Worklets 0.13.1 on 2026-10-28, and both packages are MIT licensed.

Frequently asked questions

Official sources

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