React Native Workers

Real threads for React Native. Web Worker–style API, backed by a separate Hermes runtime on its own thread — with structured-clone messaging, timers, shared memory, and full native-module access.

Documentation · Quick start · API reference · Examples

React Native runs all your JavaScript on a single JS thread, and drives UI updates from it. A long parse, a big image filter, or a tight simulation loop blocks that thread — so it can't dispatch updates and your UI stalls.

This library gives you a real one:

import { Worker } from '@ammarahmed/react-native-workers';

const worker = new Worker({
  inline: `self.onmessage = (e) => self.postMessage({ doubled: e.data * 2 });`,
});

worker.onmessage = (e) => console.log(e.data); // { doubled: 42 }
worker.postMessage(21);

It's a headless React Native: no UI, but the same JavaScript engine, the same timers and Promises, and the same native modules you already use.

Why it's different

Workers vs. Worklets

These get compared a lot, so briefly — they solve different problems and are not competitors:

• The unit differs. A worklet is a function plus its captured closure, moved into another runtime. A worker is a file with its own Metro bundle graph, so you import npm packages normally and there are no closure-capture rules to learn.
• Both give you real JS runtimes. Worklet runtimes have event loops and timers too, and Bundle Mode lets you import libraries into them. That part isn't a difference.
• The API differs. Workers speak the Web spec — new Worker(), postMessage, onmessage. Worklets are a lower-level imperative primitive for scheduling work onto a runtime, which is more flexible and less familiar.
• For animations and gestures, use Reanimated / Worklets. Their synchronous UI runtime is purpose-built and battle-tested for driving UI at 60–120fps. A message-passing worker shouldn't be your animation layer.
• For "get this work off my JS thread", workers fit. Parsing, crypto, image work, database access, network I/O — with per-worker native module instances and events that stay on the worker.

The long version, including where Worklets is ahead and corrections from their team, is in the comparison.

Install

npm install @ammarahmed/react-native-workers

Requires the New Architecture with Hermes (RN 0.81.4+, developed against 0.86). Native code is autolinked; run pod install on iOS.

Then wrap your Metro config — this is what keeps worker bundles small:

const { getDefaultConfig } = require('@react-native/metro-config');
const { withWorkers } = require('@ammarahmed/react-native-workers/metro');

module.exports = withWorkers(getDefaultConfig(__dirname));

Full setup — including the Babel plugin for file-based workers and the one-time Android native-module registration — is in the installation guide.

A tour

const worker = new Worker('./workers/heavy-task');

const worker = new Worker('./workers/task', { nativeModules: true });

// inside a worker
const emitter = new NativeEventEmitter(someNativeModule);
const sub = emitter.addListener('SomeEvent', (payload) => {
  // fires on the worker thread
});

const store = new SharedStore('session');
store.set('user', { id: 1, name: 'Ada' });
const off = store.subscribe('user', (key, value) => { /* any runtime wrote */ });

store.setIn('doc', ['user', 'age'], 31);           // encodes only the new leaf
store.subscribeIn('doc', ['user'], (path, value) => { /* ['age'], 31 */ });

// A single synchronous cell — lock-free for numbers (~17M writes/sec).
const progress = new SharedValue('anim:progress', 0);
progress.value = 0.42;

// Raw shared memory — same bytes in every runtime, zero host calls per element.
const buf = new SharedBuffer('sim', 50_000 * Float64Array.BYTES_PER_ELEMENT);
const view = new Float64Array(buf.arrayBuffer);

// worker (JSModule is a global in every worker)
new JSModule('calc', {
  add(a, b) { return a + b; },
  async fetchUser(id) { return await load(id); },
});

// host — fully typed
const calc = worker.module<Calc>('calc');
await worker.ready('calc');
const sum = await calc.add(2, 3); // 5

export const calc = defineModule<{
  worker: { add(a: number, b: number): number };
  host:   { getConfig(): Config };
  events: { progress: { percent: number } };
  state:  { status: 'idle' | 'busy' };
}>('calc');

const w = new UIWorker({ inline: `self.onmessage = (e) => { /* UI-thread JS */ };` });

Bundle size

Each worker is its own Metro graph, so import … from 'react-native' pulls the whole framework — renderer, components, Animated, virtualized-lists — into every worker that reaches it. Third-party native modules import that barrel themselves, so careful worker code alone cannot avoid it.

withWorkers() resolves react-native to a worker-sized shim inside worker graphs only. Measured on the example app (Hermes bytecode, minified):

Exports a worker cannot use (View, StyleSheet, Animated, hooks…) throw on access with a message naming the export, instead of being silently undefined.

What's supported

Structured clone (objects, arrays, cycles, typed arrays, ArrayBuffer, Date, Map, Set, RegExp, Error, BigInt), self / postMessage / onmessage / close / addEventListener, timers, Promises, structuredClone, error propagation to onerror, terminate, worker isolation, and NativeEventEmitter.

Binary data transfers instead of copying: postMessage(v, [buf]) moves the backing store, and createTransferableBuffer(n) gives you a buffer that's zero-copy on every hop.

Native modules inside a worker are isolated — their events are delivered to that worker rather than being raised on the app's runtime and copied back, their method bodies run off the worker's JS thread (Android), and peer lookups resolve to the worker's own instances. A worker's network I/O doesn't depend on the RN JS thread being free.

Also inside a worker: Expo Modules via requireNativeModule(...) on both platforms, and the experimental Thread API for running a worker's own runtime on another thread.

Limits worth knowing. Hermes has no ArrayBuffer detach, so a transferred buffer isn't neutered by the engine — this library refuses to reuse it and .detached reports true, but raw reads still succeed unless you call enableTransferGuard(). SharedArrayBuffer doesn't exist in Hermes; SharedBuffer is the shared-memory path. Native-module isolation leans on private React Native internals, all of which are listed — with what would let me delete them — in Hacks & compatibility seams.

Example app

The example/ app is a gallery of working screens — search service, image filters, downloads, sensors, parallel parsing, notes — plus a conformance suite covering the API surface. Step-by-step build-ups for each screen are in the tutorials.

Contributing

• Development workflow
• Sending a pull request

License

MIT © Ammar Ahmed