{"id":11815,"library":"react-native-worklets-core","title":"React Native Worklets Core","description":"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.","status":"active","version":"1.6.3","language":"javascript","source_language":"en","source_url":"https://github.com/margelo/react-native-worklets-core","tags":["javascript","react-native","ios","android","typescript"],"install":[{"cmd":"npm install react-native-worklets-core","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-worklets-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-worklets-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native environment.","package":"react","optional":false},{"reason":"Peer dependency for React Native environment.","package":"react-native","optional":false}],"imports":[{"note":"Used for TypeScript definitions when working with worklet functions.","symbol":"Worklet type","correct":"import type { Worklet } from 'react-native-worklets-core'"},{"note":"The plugin is configured in `babel.config.js` to transform functions marked with the `'worklet'` pragma, not imported as a runtime module.","wrong":"import 'react-native-worklets-core/plugin'","symbol":"Babel plugin","correct":"plugins: [[\"react-native-worklets-core/plugin\"]]"},{"note":"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.","wrong":"import { Worklets } from 'react-native-worklets-core'","symbol":"Worklets global object","correct":"Worklets.defaultContext.runAsync(myWorklet)"},{"note":"This hook provides a memoized function that can be called from a Worklet context to execute code back on the JavaScript (main) thread.","symbol":"useRunOnJS hook","correct":"import { useRunOnJS } from 'react-native-worklets-core'"}],"quickstart":{"code":"import React, { useEffect } from 'react';\nimport { View, Text, StyleSheet } from 'react-native';\nimport { Worklets, useRunOnJS } from 'react-native-worklets-core';\n\n// Important: Add the babel plugin to your babel.config.js:\n// module.exports = {\n//   plugins: [\n//     [\"react-native-worklets-core/plugin\"],\n//     // ... other plugins\n//   ],\n//   // ...\n// };\n\nconst logFromJS = (message) => {\n  console.log(`[JS Thread] ${message}`);\n};\n\nexport default function App() {\n  // Memoize the JS callback to be safely called from a worklet\n  const logFromJSWorklet = useRunOnJS(logFromJS, []);\n\n  useEffect(() => {\n    // Define a worklet function\n    const heavyWorklet = () => {\n      'worklet'; // The worklet pragma is crucial\n      let sum = 0;\n      for (let i = 0; i < 100000000; i++) {\n        sum += Math.sqrt(i);\n      }\n      const message = `Calculation complete: ${sum.toFixed(2)}`;\n      logFromJSWorklet(message); // Call back to JS thread from worklet\n    };\n\n    // Run the worklet on a default background context\n    Worklets.defaultContext.runAsync(heavyWorklet);\n\n    console.log('[Main App] Initiating heavy worklet...');\n  }, [logFromJSWorklet]);\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.text}>Check your Metro logs for Worklet output!</Text>\n      <Text style={styles.subText}>Heavy calculation running on a background thread.</Text>\n    </View>\n  );\n}\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: '#f0f0f0',\n  },\n  text: {\n    fontSize: 18,\n    fontWeight: 'bold',\n    marginBottom: 10,\n  },\n  subText: {\n    fontSize: 14,\n    color: '#666',\n  },\n});","lang":"typescript","description":"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."},"warnings":[{"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`).","message":"Version 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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"For 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.","severity":"breaking","affected_versions":">=1.6.3"},{"fix":"Add `['react-native-worklets-core/plugin']` to your `plugins` array in `babel.config.js` and restart Metro with `--reset-cache`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Migrate your React Native project to the New Architecture (Fabric) as per React Native's official migration guides.","message":"The `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.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The Babel plugin `react-native-worklets-core/plugin` is missing or incorrectly configured, failing to transform the worklet function.","error":"Property '_WORKLET' doesn't exist"},{"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.","cause":"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.","error":"Invariant Violation: Calling synchronous methods on native modules is not supported in JSC"},{"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.","cause":"Older versions of `react-native-worklets-core` had class naming conflicts or build script issues on Android, preventing dependent libraries from linking correctly.","error":"Android build issues: dependent libraries can't link RNWC"},{"fix":"Restart Metro Bundler with a clean cache: `yarn start --reset-cache` or `npm start -- --reset-cache`.","cause":"Often seen after installing new native modules or Babel plugins, indicating Metro's cache is stale and hasn't picked up the new configuration.","error":"Error: Metro has encountered an error: Requiring module '...' which is not enabled."}],"ecosystem":"npm"}