Guides
Comparison with react-native-worklets
How named secondary runtimes differ from Software Mansion's worklets, including Bundle Mode.
react-native-worklets (Software Mansion) and React Native Runtimes both run JavaScript off the main runtime, but they solve different problems with different execution models.
At a glance
| # | Aspect | react-native-worklets | react-native-runtimes |
|---|---|---|---|
| 1 | What runs on the other thread | Short-running functions marked 'worklet'. A Babel plugin "workletizes" them — extracts the function and its captured closure into a serializable object that is copied onto the worklet runtime. | Ordinary JS — full React component trees and whole screens. Each runtime has access to all React Native modules and components, which is what makes it possible to render complete UI on a background thread. |
| 2 | Rendering & shadow tree | ❌ Worklet runtimes can't mount React trees. UI-thread worklets (Reanimated) mutate the main tree's ShadowNodes, so they are subject to main-runtime commit locks. | ✅ <OnRuntime> / ThreadedScreen run a real React renderer per runtime with its own shadow tree — no shared ShadowNodes, so background runtimes are never blocked by main-runtime locks. |
| 3 | Bundle & module access | By default worklets only see their workletized closure — third-party imports need patches. Full-bundle access requires the experimental Bundle Mode (react-native-worklets@bundle-mode-preview, Babel bundleMode: true, temporary Metro patches). | Full bundle access is the default and only mode — Metro generates .threaded-runtime/entry.js, every runtime loads a complete bundle, so any import, third-party library, or native module just works. |
| 4 | App startup | Worklet runtimes are created from JS (createWorkletRuntime) after the main bundle has loaded — startup work stays serialized behind the main runtime. | Secondary runtimes can be started when the app process starts (prewarmBusinessRuntime / prewarm), so app initialization, hydration, and first-screen prep run in parallel with main-runtime startup. |
| 5 | Cross-thread state & communication | Shared values / Shareables plus scheduleOnUI / runOnJS; captured data is copied (serialized) between runtimes per call. | JSON-serialized props/args, typed call(fn).on('runtime'), headless tasks, plus @react-native-runtimes/state — a C++-singleton-backed Zustand-style store with synchronous reads/writes from every runtime. |
Complementary, not competing
Worklets win for synchronous, frame-precise work on the UI thread — animations and gestures, where Reanimated is built on them. React Native Runtimes wins for moving entire screens, React trees, and app-startup or business logic off the main JS thread. Many apps benefit from using both.