Registry / web-framework / react-native-worklets-core

react-native-worklets-core

JSON →
library1.6.3jsnpmunverified

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-core
INSTALL
IMPORT
SIG · REACT-NATIVE-WORKL
R
react-native-worklets-core
web-frameworkjavascriptv1.6.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Worklet type
import type { Worklet } from 'react-native-worklets-core'
Used for TypeScript definitions when working with worklet functions.
Babel plugin
plugins: [["react-native-worklets-core/plugin"]]
import 'react-native-worklets-core/plugin'
The plugin is configured in `babel.config.js` to transform functions marked with the `'worklet'` pragma, not imported as a runtime module.
Worklets global object
Worklets.defaultContext.runAsync(myWorklet)
import { Worklets } from 'react-native-worklets-core'
The `Worklets` object is often a global runtime object, providing utilities like `defaultContext`, `createContext`, and `runOnJS` for inter-thread communication. It's typically accessed directly or via hooks, not as a direct module import.
useRunOnJS hook
import { useRunOnJS } from 'react-native-worklets-core'
This hook provides a memoized function that can be called from a Worklet context to execute code back on the JavaScript (main) thread.

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.

import React, { useEffect } from 'react'; import { View, Text, StyleSheet } from 'react-native'; import { Worklets, useRunOnJS } from 'react-native-worklets-core'; // Important: Add the babel plugin to your babel.config.js: // module.exports = { // plugins: [ // ["react-native-worklets-core/plugin"], // // ... other plugins // ], // // ... // }; const logFromJS = (message) => { console.log(`[JS Thread] ${message}`); }; export default function App() { // Memoize the JS callback to be safely called from a worklet const logFromJSWorklet = useRunOnJS(logFromJS, []); useEffect(() => { // Define a worklet function const heavyWorklet = () => { 'worklet'; // The worklet pragma is crucial let sum = 0; for (let i = 0; i < 100000000; i++) { sum += Math.sqrt(i); } const message = `Calculation complete: ${sum.toFixed(2)}`; logFromJSWorklet(message); // Call back to JS thread from worklet }; // Run the worklet on a default background context Worklets.defaultContext.runAsync(heavyWorklet); console.log('[Main App] Initiating heavy worklet...'); }, [logFromJSWorklet]); return ( <View style={styles.container}> <Text style={styles.text}>Check your Metro logs for Worklet output!</Text> <Text style={styles.subText}>Heavy calculation running on a background thread.</Text> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#f0f0f0', }, text: { fontSize: 18, fontWeight: 'bold', marginBottom: 10, }, subText: { fontSize: 14, color: '#666', }, });
Debug
Known issues
breakingVersion 1.4.0 and higher of react-native-worklets-core requires React Native 0.74 or higher. This is due to added support for Nitro HybridObjects, which leverages newer React Native architecture features.
fix
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`).
affects: >=1.4.0
breakingFor React Native versions 0.82 and above, the internal Hermes VM library name has been changed from `libhermes` to `hermesvm`. This requires an update to `react-native-worklets-core` to correctly link against Hermes.
fix
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.
affects: >=1.6.3
gotchaThe Babel plugin `react-native-worklets-core/plugin` is mandatory and must be correctly configured in your `babel.config.js` file. Forgetting this step will prevent functions marked with `'worklet'` from being transformed, leading to runtime errors where worklets are not recognized.
fix
Add `['react-native-worklets-core/plugin']` to your `plugins` array in `babel.config.js` and restart Metro with `--reset-cache`.
affects: >=1.0.0
gotchaWhen integrating `react-native-worklets-core` in existing libraries or custom modules, ensure proper native linking for both iOS (Podfile) and Android (build.gradle and CMakeLists.txt) to avoid build failures or runtime crashes.
fix
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`.
affects: >=1.0.0
deprecatedThe `Worklets` library is not tested on the Legacy Architecture (Paper). It is highly recommended to migrate to the New Architecture (Fabric) for optimal compatibility and performance.
fix
Migrate your React Native project to the New Architecture (Fabric) as per React Native's official migration guides.
affects: >=1.0.0
Errors
Common errors & fixes
Property '_WORKLET' doesn't exist
The Babel plugin `react-native-worklets-core/plugin` is missing or incorrectly configured, failing to transform the worklet function.
fix
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`.
Invariant Violation: Calling synchronous methods on native modules is not supported in JSC
Attempting to run a Worklet-enabled function in an environment where the Worklet runtime is not properly initialized or available, often indicating an issue with the native module setup.
fix
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.
Android build issues: dependent libraries can't link RNWC
Older versions of `react-native-worklets-core` had class naming conflicts or build script issues on Android, preventing dependent libraries from linking correctly.
fix
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.
Error: Metro has encountered an error: Requiring module '...' which is not enabled.
Often seen after installing new native modules or Babel plugins, indicating Metro's cache is stale and hasn't picked up the new configuration.
fix
Restart Metro Bundler with a clean cache: `yarn start --reset-cache` or `npm start -- --reset-cache`.
Upgrade
Version history
1.6.3latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React Native environment.
react-nativerequiredPeer dependency for React Native environment.
Agent activity
21 hits · last 30 days
node
14
OpenAI (training)
3
Meta
1
Resources
react-native-worklets-core — npm install react-native-worklets-core · libregistry