Skip to content

callstackincubator/apex-software-factory / .agents/skills/swm-react-native-best-practices

swm-react-native-best-practices

Verified

Software Mansion's best practices for React Native and Expo on the New Architecture: Reanimated 4 animations, Gesture Handler, react-native-svg, and react-native-worklets threading. Read the sub-skill in references/ that matches the topic.

references/multithreading/index.md

View on GitHub
---
name: multithreading
description: "Software Mansion's best practices for multithreading in React Native apps using react-native-worklets. Use when running JavaScript on multiple threads, offloading heavy computation from the JS thread, communicating between runtimes, or sharing data across threads. Trigger on: 'worklet', 'worklets', 'react-native-worklets', 'runOnUI', 'runOnJS', 'scheduleOnUI', 'scheduleOnRN', 'scheduleOnRuntime', 'createWorkletRuntime', 'background thread', 'UI thread', 'worker runtime', 'Serializable', 'Synchronizable', 'multithreading', 'parallel execution', 'offload computation', 'background processing', 'Bundle Mode', or any request to move work off the JS thread in a React Native app."
---

# 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.

```tsx
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 usage, import forwarding, testing with Jest, feature flags, troubleshooting |

For enabling Bundle Mode in an app (babel option, metro config, mandatory metro/metro-runtime patches, "Failed to get the SHA-1" errors), upstream has a dedicated sub-skill. (Apex: the Bundle Mode sub-skill is not vendored; enabling it patches Metro and changes the Babel setup, which a feature change never does.)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall