Reanimated 4 + react-native-worklets in Production: Migrating Off Reanimated 3 Without Breaking Your Animations

The single biggest gotcha is the Babel plugin. If you leave react-native-reanimated/plugin in your babel.config.js, your worklets silently stop being transformed and you get cryptic runtime errors about functions not being workletized. Swap it for react-native-worklets/plugin.

Do I have to be on the New Architecture for Reanimated 4?

Yes. Reanimated 4 does not run on the old bridge-based architecture at all, so the New Architecture migration is a hard prerequisite, not an optional cleanup. If your app still has newArchEnabled=false, you need to fix that first.

This is the part people underestimate. The Reanimated upgrade is small. The New Architecture upgrade can be large if your app leans on old native modules, custom view managers, or libraries that never shipped Fabric components. I treat them as two separate migrations and I do the New Architecture one first, with Reanimated still on 3, so I only debug one variable at a time.

If you are doing this on an older app, I wrote up the full forced-migration path in migrating a legacy app to 0.85 when New Architecture is the only option ↗. Get that green before you touch Reanimated. The order that worked for me:

1. Enable New Architecture, ship it, confirm gestures and animations still behave on Reanimated 3.


2. Only then bump Reanimated to 4 and add react-native-worklets.

How do I install the react-native-worklets split correctly?

Install react-native-reanimated@4 and react-native-worklets together, then point your Babel plugin at the worklets package. Do those two things in the same commit so the runtime and the transform always agree.

npm install react-native-reanimated@^4.0.0 react-native-worklets
## or
yarn add react-native-reanimated@^4.0.0 react-native-worklets

Then update babel.config.js. The plugin still has to be listed last in the plugins array, same rule as Reanimated 3, just under a new name:

// babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    // ...your other plugins
    'react-native-worklets/plugin', // MUST be last
  ],
};

After that, clear every cache. This is not superstition. Stale Metro and Babel caches are the number one reason a correct migration looks broken:

watchman watch-del-all
rm -rf node_modules
npm install
npm start -- --reset-cache
cd ios && pod install && cd ..

If you use Expo, run npx expo install react-native-reanimated react-native-worklets so the versions match your SDK, and prebuild again.

One sanity check I always run: search the codebase for the old plugin string. If react-native-reanimated/plugin appears anywhere (including in a forgotten .babelrc or a monorepo package), it will fight the new one.

Will my existing useAnimatedStyle and useSharedValue code still work?

Yes. The imperative API is the same surface in Reanimated 4, so useSharedValue, useAnimatedStyle, withSpring, withTiming, useAnimatedGestureHandler, and friends keep working. You are not rewriting your animations, you are re-pointing the runtime.

This is the reassuring part for a gesture-heavy app. My swipe-to-dismiss and drag-to-reorder code, all built on shared values and useAnimatedStyle, compiled and ran without logic changes once the install and Babel plugin were correct. Here is the kind of imperative gesture code that carried over untouched:

import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from 'react-native-reanimated';
import { Gesture, GestureDetector } from 'react-native-gesture-handler';

function DraggableCard() {
  const translateX = useSharedValue(0);

  const pan = Gesture.Pan()
    .onChange((e) => {
      translateX.value += e.changeX;
    })
    .onEnd(() => {
      translateX.value = withSpring(0);
    });

  const style = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={style} />
    </GestureDetector>
  );
}

The thing to watch is that if you previously imported worklet utilities directly from Reanimated internals (runOnJS, runOnUI, or low-level worklet helpers in some setups), some of those now resolve through the worklets package. The public Reanimated re-exports still work for the common cases, but if you reached into deep import paths, expect to fix a few import lines. Run a TypeScript build and let the compiler list them for you.

What is the new CSS-style animation API and when should I use it?

The CSS-style API lets you declare transitions and keyframe-style animations as style properties instead of wiring up shared values, and it is the right choice for simple, declarative state changes. For complex gestures that track a finger frame by frame, stick with the imperative API.

The mental model: simple enter/exit, hover, and state-driven transitions become declarative, closer to how you would write a CSS transition on the web. Here is a layout transition expressed the new way versus the old way.

// New: CSS-style declarative transition
<Animated.View
  style={{
    width: expanded ? 300 : 100,
    transitionProperty: 'width',
    transitionDuration: 300,
  }}
/>

// Old: imperative, still valid
const width = useSharedValue(100);
useEffect(() => {
  width.value = withTiming(expanded ? 300 : 100, { duration: 300 });
}, [expanded]);
const style = useAnimatedStyle(() => ({ width: width.value }));
return <Animated.View style={style} />;

My rule of thumb for picking between them:

• Use the CSS-style API for state-driven transitions, simple loops, and anything where you would otherwise write a short withTiming in a useEffect. Less code, fewer shared values to manage.


• Use the imperative API for gestures, anything that reads event.changeX per frame, physics you tune by hand, and animations that have to coordinate with other shared values.

How does React Native 0.85's Shared Animation Backend change what I should hand-roll?

RN 0.85 introduced a Shared Animation Backend, which gives animation libraries a common low-level path to drive animations on the native side. The practical takeaway: lean on the library and stop hand-rolling native-driven workarounds you wrote to dodge old Animated limitations.

In the bridge era, plenty of teams (mine included) wrote custom native animation hacks or useNativeDriver gymnastics to keep certain animations off the JS thread. With the Shared Animation Backend in 0.85 and Reanimated 4 sitting on the New Architecture, that class of workaround is mostly obsolete. The backend is plumbing that the libraries consume, not an API you call directly in app code, so the migration action is subtraction: delete the clever stuff and let Reanimated drive.

Concretely, during this migration I:

• Removed a couple of old Animated.Value with useNativeDriver: true paths that existed only to avoid JS-thread jank, and moved them to shared values.


• Deleted a native-side animation patch a previous developer had added to force 60fps on a progress bar.


• Stopped manually throttling gesture updates, since worklets on the UI thread already run them off the JS thread.

What is a safe migration order and rollback plan?

The safest path is: confirm New Architecture works on Reanimated 3, then bump Reanimated and worklets in one commit, then audit your hand-rolled animations. Keep each step behind its own commit so you can bisect a regression in minutes.

Here is the checklist I follow: