react-native-worklets-core is a foundational library providing a robust Worklet runner for React Native applications. It enables developers to define and execute JavaScript functions (known as Worklets) on a separate UI or native thread, distinct from the main JavaScript thread. This capability is crucial for achieving smooth animations and performance-intensive tasks without blocking the UI. The current stable version is 1.6.3, with an active development cadence including regular bug fixes and feature releases, alongside ongoing beta development for version 2.0.0. Unlike React Native Reanimated, which deeply integrates Worklets into its animation API, react-native-worklets-core aims for a more flexible, lower-level Worklet architecture. This design allows it to serve primarily as a peer dependency for other complex C++ integrated modules like react-native-vision-camera, react-native-wishlist, and react-native-skia, providing a portable and extensible Worklet runtime that facilitates easier integration with diverse native libraries and custom UI components.
npm install react-native-worklets-coreVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define a Worklet function using the `'worklet'` pragma, execute it on a background thread using `Worklets.defaultContext.runAsync`, and safely call back to the main JavaScript thread using the `useRunOnJS` hook. It also highlights the essential Babel plugin configuration.
Upgrade your React Native project to version 0.74 or newer. Ensure your project's native code is rebuilt after upgrading (e.g., `npx react-native run-ios` or `npx react-native run-android`).
Ensure you are using `react-native-worklets-core` version 1.6.3 or newer when targeting React Native 0.82+ to avoid linking issues related to Hermes.
Add `['react-native-worklets-core/plugin']` to your `plugins` array in `babel.config.js` and restart Metro with `--reset-cache`.
For iOS, run `cd ios && pod install`. For Android, verify `implementation project(":react-native-worklets-core")` in `build.gradle` and `find_package(react-native-worklets-core REQUIRED CONFIG)` and `target_link_libraries( ... react-native-worklets-core::rnworklets )` in `CMakeLists.txt`.Migrate your React Native project to the New Architecture (Fabric) as per React Native's official migration guides.
Verify `['react-native-worklets-core/plugin']` is present in your `babel.config.js` under the `plugins` array. Ensure you have restarted Metro with `yarn start --reset-cache` or `npm start -- --reset-cache`.
Confirm that the `react-native-worklets-core` native modules are correctly linked and built for your platform. For iOS, ensure `pod install` was run. For Android, check `build.gradle` and `CMakeLists.txt` configurations. Clear Metro cache and rebuild native modules.
Upgrade to `react-native-worklets-core` version 1.6.1 or newer, which includes fixes for Android build issues and class naming conflicts (renamed `WorkletsCore`). Clean your Android build cache (`./gradlew clean`) and rebuild.
Restart Metro Bundler with a clean cache: `yarn start --reset-cache` or `npm start -- --reset-cache`.