React Native Worklets is a fundamental library providing low-level multithreading capabilities for React Native applications. It enables JavaScript functions, known as 'worklets', to execute directly on the UI thread or other background threads, bypassing the JavaScript thread bottleneck. This is crucial for achieving smooth animations, gestures, and other performance-sensitive operations that might otherwise cause UI jank. The library is closely integrated with and often used as a core component of `react-native-reanimated`. The current stable version is 0.8.1, with releases often coinciding with major `react-native-reanimated` updates. A key differentiator is its `Shareable` memory type, introduced in v0.8.0, which allows for efficient and safe data sharing between threads. It focuses on raw performance and thread control, rather than high-level animation APIs, serving as a building block for more complex libraries.
npm install react-native-workletsVerified import paths — ran on the pinned version, not inferred.
This example demonstrates how to define a worklet and execute a computationally heavy task on the UI thread using `runOnUI`, then pass the result back to the JavaScript thread with `runOnJS` to update React state, preventing UI freezes.
Ensure your project's `react-native` version matches the peer dependency range specified in `react-native-worklets`'s `package.json`. You might need to upgrade or downgrade `react-native` or wait for a compatible `react-native-worklets` release.
Ensure your `babel.config.js` includes the necessary presets and plugins, usually handled automatically if `react-native-reanimated` is correctly installed. Check the `react-native-reanimated` documentation for the recommended Babel setup.
For versions prior to 0.8.0, ensure worklets only use primitive values or global/imported functions. For v0.8.0+, use `Shareable` types for complex data structures that need to be passed into worklets. Avoid capturing `useState` setters or `useRef` objects directly.
For full functionality and reliable testing, use Expo Development Builds or run your application in a bare React Native project setup rather than Expo Go.
Verify your `babel.config.js` includes the `react-native-reanimated/plugin` (if using Reanimated) or equivalent worklet transformation plugin. Ensure the `'worklet'` directive is present at the top of any function intended to run on the UI thread.
Adjust your `react-native` version to be within the compatible range (e.g., `npm install react-native@0.81.0` or `yarn add react-native@0.81.0`) or update `react-native-worklets` to a version compatible with your current React Native.
Import `SharedValue` and related animation primitives from `react-native-reanimated`, not `react-native-worklets`. `react-native-worklets` provides the low-level threading primitives, while Reanimated builds higher-level animation APIs on top of it.