React Native Worklets Core

1.6.3 · active · verified Sun Apr 19

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.

Common errors

Warnings

Install

Imports

Quickstart

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',
  },
});

view raw JSON →