React Native Reanimated and Worklets

This repository contains two primary libraries designed for high-performance React Native applications:

• React Native Reanimated: A library for creating smooth animations and interactions.
• React Native Worklets: A library that enables multi-threaded JavaScript execution in React Native applications.

Reanimated 4 is the current major version.

The Worklets library operates using two primary types of runtimes: the React Native Runtime and Worklet Runtimes.

• RN Runtime: The standard JavaScript runtime spawned by React Native (the JS Thread). It is the only runtime with access to React Native APIs, app state, and components. There is exactly one RN Runtime per app.
• Worklet Runtime: A specialized JavaScript runtime spawned by the Worklets library, pre-configured to execute worklets. It does not share memory with the RN Runtime but communicates via specific APIs. Each Worklet Runtime is identified by a unique runtimeId used for communication or creating Shareables.

Worklets can operate in two modes:

1. Bundle Mode: The recommended mode where worklets have access to the full JS bundle and pre-compiled bytecode optimizations.
2. Legacy Eval Mode: The former method where each worklet is serialized as a string and evaluated individually on the Worklet Runtime. This is currently the default mode, but it is strongly recommended to opt out of it in favor of Bundle Mode.

The repository is organized as a monorepo. Key directories include:

• apps/: Contains example applications (e.g., fabric-example for New Architecture, web-example for Web, macos-example, next-example, tvos-example, and common-app for shared source).
• packages/: Contains the core libraries:
  • react-native-reanimated: The main package, including android (native), apple (iOS native), Common (shared C++), scripts (CI), and src (JS source).
  • react-native-worklets: The worklets package.
  • eslint-plugin-reanimated: The ESLint plugin.
• docs/: Contains documentation for Reanimated (docs-reanimated) and Worklets (docs-worklets).

Serializable is a shared memory type used to hold immutable values that can be serialized and deserialized across different JavaScript Runtimes. It enables passing JavaScript values between Runtimes by ensuring data is correctly transferred and reconstructed.

Important constraints:

• The reference is a wrapper and cannot be manipulated directly as it does not represent a standard JavaScript object.
• You cannot pass JavaScript values to other Runtimes without prior serialization.
• Functions that are not worklets are serialized as references to function instances on their respective Runtime; they can be passed around but cannot be invoked on other runtimes.

Worklets are functions that can be executed on both the JavaScript thread and the UI thread. This allows Reanimated to perform smooth animations by running logic directly on the UI thread, avoiding expensive communication between threads.

A worklet is defined as an Arrow Function Expression, Function Declaration, Function Expression, or Object Method that contains a 'worklet' directive at the very top of its body.

const foo = () => {
  'worklet';
  console.log('Hello from the UI thread');
}

Understanding the threading model is crucial for performance:

• JavaScript thread (JS thread): The primary environment for the React Native Runtime. It handles business logic, state management, and JavaScript event handling.
• UI thread (Main thread): Responsible for handling user interface updates. Worklets are often used to move high-frequency logic from the JS thread to this thread to ensure smooth animations.