react-native-background-workers [WIP]

High-level, type-safe Web Workers API for React Native New Architecture.

Run heavy computations (ML inference, image processing, complex algorithms, large data parsing) in separate background runtimes without blocking the main JS thread or UI.

Built on top of react-native-worklets (Software Mansion) but hides all low-level details — no 'worklet' directives, no makeShareable, no runOnRuntime boilerplate.

Features

• Declarative hooks — useBackgroundWorker and useWorker
• Promise-based messaging — worker.send(msg) returns a typed Promise
• Setup lifecycle — isReady / setupError let you guard UI until the worker is initialized
• Event system — addEventListener for message, error, progress
• Worker Pool — share runtimes across multiple hooks with WorkerPool.configure()
• Babel plugin — auto-workletizes your callbacks, zero config needed
• Presets — factory functions for common use-cases (ML inference, image processing)
• TypeScript-first — fully typed inputs, outputs, and events

Installation

yarn add react-native-background-workers react-native-worklets

For iOS, install native dependencies:

cd ios && pod install

Babel Plugin Setup

Add both plugins to your babel.config.js (order matters):

module.exports = {
  // ...
  plugins: [
    'react-native-background-workers/plugin',  // must come first
    'react-native-worklets/plugin',
  ],
};

The background-workers plugin auto-injects 'worklet' directives into your setup, onMessage, and task callbacks so you never need to write them manually.

Quick Start

useBackgroundWorker — long-lived worker

import { useBackgroundWorker } from 'react-native-background-workers';

function MyComponent() {
  const { worker, isReady, setupError } = useBackgroundWorker({
    name: 'StatsWorker',
    setup: () => {
      globalThis.cache = new Map();
    },
    onMessage: (msg: { numbers: number[] }) => {
      const sum = msg.numbers.reduce((a, b) => a + b, 0);
      return { sum, avg: sum / msg.numbers.length };
    },
  });

  if (setupError) return <Text>Setup failed: {setupError.message}</Text>;
  if (!isReady) return <ActivityIndicator />;

  const handlePress = async () => {
    const result = await worker.send({ numbers: [1, 2, 3, 4, 5] });
    console.log(result); // { sum: 15, avg: 3 }
  };

  return <Button onPress={handlePress} title="Compute" />;
}

useWorker — simple one-off task

import { useWorker } from 'react-native-background-workers';

function MyComponent() {
  const { run, isLoading, data, error } = useWorker(
    (n: number) => {
      let total = 0;
      for (let i = 0; i < n; i++) total += Math.sqrt(i);
      return total;
    },
    [],
    { timeout: 5000 }
  );

  return (
    <>
      <Button onPress={() => run(1_000_000)} title="Run" disabled={isLoading} />
      {data != null && <Text>Result: {data}</Text>}
    </>
  );
}

Pool Mode — shared runtimes

import { WorkerPool, useBackgroundWorker } from 'react-native-background-workers';

// Call once at app startup to set the max number of shared runtimes
WorkerPool.configure(4);

function MyComponent() {
  const { worker: workerA } = useBackgroundWorker(
    { name: 'A', onMessage: (msg) => `processed: ${msg}` },
    { dedicated: false }
  );

  const { worker: workerB } = useBackgroundWorker(
    { name: 'B', onMessage: (msg) => msg.toUpperCase() },
    { dedicated: false }
  );

  // Both workers share from a pool of up to 4 runtimes
}

Worker Pool Stats

import { WorkerPool } from 'react-native-background-workers';

const stats = WorkerPool.shared().getStats();
// {
//   dedicatedCount: 2,
//   dedicatedNames: ['HeavyWorker', 'MLWorker'],
//   pooledCount: 3,
//   pooledMaxSize: 4,
//   poolSlots: [
//     { slotName: 'PoolSlot-0', workers: [...], totalPending: 1 },
//     ...
//   ],
//   workers: [
//     { name: 'A', type: 'pooled', poolSlot: 'PoolSlot-0', pendingTasks: 1 },
//     ...
//   ],
//   totalRuntimes: 5,
// }

API Reference

useBackgroundWorker<TInput, TOutput>(options, config?)

Creates a long-lived background worker.

Options:

| Property | Type | Description | |---|---|---| | name | string? | Debug name (shown in profilers and pool stats) | | setup | () => void \| Promise<void> | Runs once when the runtime is created | | onMessage | (msg: TInput) => TOutput | Message handler, return value is sent back | | onError | (error: Error) => void | Error handler inside the worker |

Config:

| Property | Type | Default | Description | |---|---|---|---| | dedicated | boolean | true | true = own runtime, false = use shared pool | | autoTerminateOnUnmount | boolean | true | Auto-terminate on component unmount |

Returns UseBackgroundWorkerResult<TInput, TOutput>:

| Property | Type | Description | |---|---|---| | worker | BackgroundWorker<TInput, TOutput> | The worker instance | | isReady | boolean | false while setup is running; true when complete (or if no setup) | | setupError | Error \| null | The error if setup threw; null otherwise |

worker methods:

| Method | Description | |---|---| | send<T>(msg) | Send message and await typed response | | postMessage(msg) | Fire-and-forget send | | addEventListener(type, fn) | Listen for 'message', 'error', 'progress' | | removeEventListener(type, fn) | Remove a listener | | terminate() | Stop the worker and free the runtime | | isTerminated() | Check if worker has been terminated | | isReady | Whether setup completed successfully | | setupError | The setup error, if any |

useWorker<TInput, TOutput>(task, deps?, config?)

Simple hook for one-off computations.

| Parameter | Type | Description | |---|---|---| | task | (input: TInput) => TOutput | The function to run in background | | deps | DependencyList? | React dependency list |

Config:

| Property | Type | Default | Description | |---|---|---|---| | timeout | number? | -- | Timeout in milliseconds | | dedicated | boolean | true | true = own runtime, false = use shared pool | | name | string? | -- | Worker name for pool stats tracking |

Returns:

| Property | Type | Description | |---|---|---| | run(input) | (input: TInput) => Promise<TOutput> | Execute the task | | isLoading | boolean | Whether a task is running | | data | TOutput \| null | Last successful result | | error | Error \| null | Last error | | cancel() | () => void | Cancel the current task |

WorkerPool

Global singleton for managing shared runtimes.

| Method | Description | |---|---| | WorkerPool.configure(maxSize) | Set max pool size. Call once at app startup, before any pool workers are created. | | WorkerPool.shared() | Get the singleton instance | | pool.getStats() | Get live stats: dedicated/pooled counts, slot details, per-worker pending tasks | | pool.getWorkerStatus(name) | Look up a specific worker by name |

Presets

createInferenceWorker(options)

import { createInferenceWorker } from 'react-native-background-workers';

const mlWorker = createInferenceWorker({
  name: 'TFLite',
  loadModel: () => { /* load model into globalThis */ },
  predict: (input) => { /* run inference, return result */ },
});

const result = await mlWorker.infer(tensorData);

createImageProcessingWorker(options)

import { createImageProcessingWorker } from 'react-native-background-workers';

const imgWorker = createImageProcessingWorker({
  name: 'ImageProcessor',
  process: (image) => { /* process image, return result */ },
});

const result = await imgWorker.processImage(imageData);

Usage with Expo

This library requires native code (react-native-worklets contains C++ TurboModules), so Expo Go is not supported. You must use a development build.

Setup

npx expo install react-native-background-workers react-native-worklets

Add the Babel plugins to your babel.config.js:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      'react-native-background-workers/plugin',
      'react-native-worklets/plugin',
    ],
  };
};

Generate native projects and build:

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

Running the Example App

The repo ships with a full demo app under example/ that showcases every API.

Prerequisites

• Node.js >= 18
• Yarn v1 (npm install -g yarn)
• Xcode 16+ (for iOS)
• CocoaPods (gem install cocoapods)
• Android SDK / Android Studio (for Android)

Setup

# 1. Clone the repo
git clone https://github.com/DimaIvashchuk/react-native-background-workers.git
cd react-native-background-workers

# 2. Install root dependencies
yarn install

# 3. Install example dependencies
cd example
yarn install

# 4. Install iOS native pods
cd ios
pod install
cd ../..

Run on iOS

yarn ios

Run on Android

yarn android

Start Metro Bundler Manually

yarn start

What the Example Demonstrates

| Demo | API | Description | |---|---|---| | Heavy Computation | useBackgroundWorker | Sums 1 billion numbers in a dedicated worker — UI stays responsive. Shows isReady / setup lifecycle. | | Setup Error | useBackgroundWorker | Intentionally failing setup to demonstrate setupError handling and send() guard. | | Simple Task | useWorker | Computes sqrt(0) + ... + sqrt(10M) as a one-off background task with timeout and cancel. | | Pool Mode | useBackgroundWorker | 5 workers (prime, hash, fib, sort, collatz) sharing 3 pool slots in parallel. | | Worker Stats | WorkerPool.shared().getStats() | Live view of all runtimes — dedicated names, pool slots, per-worker pending tasks. |

Architecture

User Code (hooks)
    |
    v
useBackgroundWorker / useWorker
    |
    v
BackgroundWorkerImpl  ---- WorkerPool (when dedicated: false)
    |                           |
    v                           v
react-native-worklets APIs
    |
    v
Worker Runtime(s)  <- separate JS threads

Key concepts:

• Each BackgroundWorkerImpl wraps one WorkletRuntime created via createWorkletRuntime()
• send() uses runOnRuntimeAsync() for Promise-based communication
• Errors are caught inside the worklet (where Error is still intact) and returned as plain strings to avoid broken serialization across the runtime boundary
• postMessage() is fire-and-forget via send().catch()
• The WorkerPool lazily creates runtimes (up to configured max) and distributes work via round-robin with least-pending preference
• State sharing between setup and onMessage happens through globalThis of the worker runtime (each runtime has its own isolated global scope)

Important Notes

Worklet Runtime Limitations

Worker runtimes are bare Hermes JS engines. They do not have access to browser or React Native globals such as fetch, setTimeout, XMLHttpRequest, or the console object. Workers are designed for CPU-bound tasks only — pure computation, data transformation, and number crunching.

State Sharing

setup and onMessage run as separate worklet invocations on the same runtime. They cannot share variables via JavaScript closure. Use globalThis instead:

const { worker } = useBackgroundWorker({
  setup: () => {
    globalThis.model = loadModel();
  },
  onMessage: (msg) => {
    return globalThis.model.predict(msg);
  },
});

Serialization

Arguments passed to send() / postMessage() must be serializable (numbers, strings, plain objects, arrays). Functions and class instances cannot be sent as messages.

Development

# Build the library (compiles src/ -> lib/ via tsc)
yarn build

# Build in watch mode
yarn build:watch

# Type-check without emitting
yarn typecheck

# Lint source and example
yarn lint

# Auto-fix lint issues
yarn lint:fix

Requirements

• React Native 0.76+ (New Architecture enabled)
• react-native-worklets >= 0.8.0
• Expo SDK 52+ (if using Expo, with development build)

License

MIT