{"id":11816,"library":"react-native-worklets","title":"React Native Worklets","description":"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.","status":"active","version":"0.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/software-mansion/react-native-reanimated","tags":["javascript","react-native","react","native","worklets","typescript"],"install":[{"cmd":"npm install react-native-worklets","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-worklets","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-worklets","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"React Native core dependency.","package":"react","optional":false},{"reason":"Required for Babel plugin to transform JavaScript functions into worklets.","package":"@babel/core","optional":false},{"reason":"Core React Native runtime dependency. Strict version range.","package":"react-native","optional":false},{"reason":"Metro bundler configuration for React Native projects.","package":"@react-native/metro-config","optional":false}],"imports":[{"note":"Used to execute a JavaScript function on the UI thread. The function must be a worklet.","wrong":"const { runOnUI } = require('react-native-worklets');","symbol":"runOnUI","correct":"import { runOnUI } from 'react-native-worklets';"},{"note":"Used to execute a worklet (or a part of it) back on the JavaScript thread from a UI thread context.","wrong":"const runOnJS = require('react-native-worklets').runOnJS;","symbol":"runOnJS","correct":"import { runOnJS } from 'react-native-worklets';"},{"note":"Explicitly marks a function as a worklet. Often, functions declared with 'worklet' directive are automatically transformed by Babel.","wrong":"import makeWorklet from 'react-native-worklets';","symbol":"makeWorklet","correct":"import { makeWorklet } from 'react-native-worklets';"},{"note":"Type import for the `Shareable` memory type, introduced in v0.8.0, for type-checking shared values.","symbol":"Shareable","correct":"import type { Shareable } from 'react-native-worklets';"}],"quickstart":{"code":"import { runOnUI, runOnJS, makeWorklet } from 'react-native-worklets';\nimport React, { useEffect, useState } from 'react';\nimport { Text, View, Button, StyleSheet } from 'react-native';\n\nconst calculateHeavyValue = makeWorklet((input) => {\n  'worklet';\n  let sum = 0;\n  for (let i = 0; i < 1_000_000_000; i++) {\n    sum += Math.random() * input;\n  }\n  return sum;\n});\n\nfunction App() {\n  const [result, setResult] = useState(0);\n  const [loading, setLoading] = useState(false);\n\n  const startCalculation = () => {\n    setLoading(true);\n    runOnUI(() => {\n      console.log('Calculating on UI thread...');\n      const heavyResult = calculateHeavyValue(10);\n      runOnJS(setResult)(heavyResult);\n      runOnJS(setLoading)(false);\n      console.log('Calculation finished on UI thread.');\n    })();\n  };\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.title}>Worklets Demo</Text>\n      <Text style={styles.resultText}>Result: {result.toFixed(2)}</Text>\n      <Button\n        title={loading ? 'Calculating...' : 'Start Heavy Calculation'}\n        onPress={startCalculation}\n        disabled={loading}\n      />\n      {loading && <Text style={styles.loadingText}>Please wait...</Text>}\n    </View>\n  );\n}\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    padding: 20,\n  },\n  title: {\n    fontSize: 24,\n    fontWeight: 'bold',\n    marginBottom: 20,\n  },\n  resultText: {\n    fontSize: 18,\n    marginVertical: 10,\n  },\n  loadingText: {\n    fontSize: 16,\n    color: 'gray',\n    marginTop: 10,\n  },\n});\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"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.","message":"The `react-native-worklets` package has strict peer dependencies on `react-native` versions, specifically `0.81 - 0.85`. Installing with incompatible versions will lead to build failures or runtime errors.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"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.","message":"To use worklets effectively, a Babel plugin (`@babel/plugin-transform-react-jsx` combined with the worklets preset or similar in `react-native-reanimated`) is typically required to transform JavaScript functions into worklets with the `'worklet'` directive. Without proper Babel configuration, worklets will not be recognized by the native modules.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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.","message":"Worklets cannot capture arbitrary variables from their lexical scope. Only 'capture-by-value' primitives (numbers, strings, booleans, null, undefined) or objects marked as `Shareable` (since v0.8.0) can be used. Attempting to capture complex objects or functions directly will result in runtime errors.","severity":"breaking","affected_versions":"<0.8.0"},{"fix":"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.","message":"When developing with Expo Go, certain native module features, including `react-native-worklets`'s static feature flags, might not be fully supported. This can lead to unexpected behavior or limitations compared to standalone builds.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"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.","cause":"The Babel plugin responsible for transforming worklets (e.g., from `react-native-reanimated`'s Babel preset) is not configured correctly or is missing. The function executed on the UI thread was not properly compiled as a worklet.","error":"Invariant Violation: A JavaScript function was called on the UI thread without being marked as a Worklet. This can happen if the Worklets Babel plugin isn't installed or configured correctly."},{"fix":"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.","cause":"The installed version of `react-native` in your project does not match the peer dependency requirements of `react-native-worklets`.","error":"Error: Incompatible `react-native` version. `react-native-worklets` requires `react-native@^0.81.0`."},{"fix":"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.","cause":"`SharedValue` is a concept from `react-native-reanimated` that relies on `react-native-worklets`'s underlying mechanisms (like `Shareable`), but it's not directly exported by `react-native-worklets` itself. You're trying to use a Reanimated concept directly from `react-native-worklets`.","error":"ReferenceError: Can't find variable: SharedValue"}],"ecosystem":"npm"}