software-mansion-labs/multithreading

React Native Multithreading with Worklets

Software Mansion's production multithreading patterns for React Native using react-native-worklets.

React Native Worklets lets you run JavaScript code in parallel across multiple threads and runtimes. It powers Reanimated, Gesture Handler, and Skia under the hood.

Version Check

Before answering any multithreading question, check that react-native-worklets is up to date:

1. Read the user's package.json to find the installed react-native-worklets version.
2. Run npm view react-native-worklets version to get the latest published version.
3. If the installed version is older than the latest, inform the user and recommend upgrading before proceeding with implementation advice.

Runtime Model

React Native apps have three kinds of runtimes. Picking the right target is the first decision:

What does the work need?
├── Respond to native events or drive animations on the same frame?
│   └── UI Runtime (main thread, one per app)
├── Heavy computation, data processing, or background tasks?
│   └── Worker Runtime (custom thread, many per app)
└── Access React state, navigation, or RN APIs?
    └── RN Runtime (JS thread, one per app)

Runtimes do not share memory. Data crosses runtime boundaries through serialization (immutable copies) or Synchronizable (shared mutable state).

API Decision Tree

Need to run code on a different runtime?
├── Fire-and-forget (no return value needed)?
│   ├── Target is UI Runtime  → scheduleOnUI(fn, ...args)
│   ├── Target is RN Runtime  → scheduleOnRN(fn, ...args)
│   └── Target is Worker      → scheduleOnRuntime(runtime, fn, ...args)
├── Need the return value asynchronously (Promise)?
│   ├── Target is UI Runtime  → await runOnUIAsync(fn, ...args)
│   └── Target is Worker      → await runOnRuntimeAsync(runtime, fn, ...args)
└── Need the return value synchronously (blocks caller)?
    ├── Target is UI Runtime  → runOnUISync(fn, ...args)
    └── Target is Worker      → runOnRuntimeSync(runtime, fn, ...args)

Critical Rules

The 'worklet' directive: functions that run on Worklet Runtimes must be workletized. Add 'worklet'; as the first statement in the function body. Callbacks passed to scheduleOnUI, scheduleOnRuntime, and similar APIs are autoworkletized by the Babel plugin.

function computeOnUI() {
  'worklet';
  return 2 + 2;
}

Don't call scheduling APIs from the wrong runtime: scheduleOnUI, runOnUISync, runOnUIAsync, runOnRuntimeSync, runOnRuntimeAsync, scheduleOnRuntime can only be called from the RN Runtime (unless Bundle Mode is enabled). Calling them from a Worklet Runtime throws an error.

Closures are copied, not shared: when a worklet runs on a different runtime, its closure variables are serialized at invocation time. Mutating the original variable after scheduling has no effect on the worklet's copy.

Deprecated APIs: runOnUI is replaced by scheduleOnUI. runOnJS is replaced by scheduleOnRN. runOnRuntime is replaced by scheduleOnRuntime. The new APIs pass arguments directly instead of returning a curried function.

References

Load at most one reference file per question.

| File | Load when question is about | |------|------------------------------| | threading-api.md | Scheduling work across runtimes, creating Worker Runtimes, sync vs async execution, migrating from deprecated APIs | | shared-memory.md | Passing data between runtimes, closures in worklets, Serializable, Synchronizable, shared mutable state | | setup-and-advanced.md | Installing worklets, Babel plugin config, Bundle Mode, testing with Jest, feature flags, troubleshooting |