createWorkletRuntime

createWorkletRuntime lets you create a new JS runtime which can be used to run worklets possibly on different threads than JS or UI thread. Use this function if you need to integrate with Worklet Runtimes in C++.

The return value represents the runtime. You can pass it to the C++ side using JSI (JavaScript Interface) for further operations.

Reference

Usage in JavaScript

import { createWorkletRuntime } from 'react-native-worklets';

function App() {
  const runtime = createWorkletRuntime({
    name: 'background',
    initializer: () => {
      'worklet';
      console.log('Runtime initialized!');
    },
  });
}

Usage in C++

auto runtime = reanimated::extractWorkletRuntime(rt, runtimeValue);

jsi::Runtime &rt = runtime->getJSIRuntime();

auto worklet = reanimated::extractShareableOrThrow<reanimated::ShareableWorklet>(rt, workletValue);

runtime->runGuarded(worklet, ...args);

Type definitions

type WorkletRuntime = {
  __hostObjectWorkletRuntime: never;
  readonly name: string;
  readonly runtimeId: number;
};

type WorkletRuntimeConfig = {
  name?: string;
  initializer?: () => void;
  animationQueuePollingRate?: number;
  enableEventLoop?: true;
  queue?: 'default' | object | null;
};

function createWorkletRuntime(
  config?: WorkletRuntimeConfig
): WorkletRuntime;

Arguments

config

Runtime configuration object.

name

A name of the runtime used in debugging. Defaults to 'anonymous'.

initializer

An optional worklet that will be run synchronously on the same thread immediately after the runtime is created. It can be used to inject some global variables or functions into the runtime.

animationQueuePollingRate

Time interval in milliseconds between polling of frame callbacks scheduled by requestAnimationFrame. Defaults to 16.

enableEventLoop

Determines whether to enable the default event loop. Defaults to true. When enabled, the runtime provides setTimeout, setImmediate, setInterval, requestAnimationFrame, queueMicrotask, clearTimeout, clearInterval, clearImmediate, and cancelAnimationFrame.

queue

Controls the queue used for scheduling worklets on this runtime. Defaults to 'default'.

• 'default': use the built-in queue implementation.
• An object implementing the C++ AsyncQueue interface from <worklets/RunLoop/AsyncQueue.h>: use the provided custom queue.
• null: do not attach any queue to the Runtime. Keep in mind that this will effectively disable all asynchronous features like Promises, setTimeout etc. Use it if you're going to implement the event-loop for the Runtime yourself.

Returns

createWorkletRuntime returns WorkletRuntime which is a jsi::HostObject<reanimated::WorkletRuntime>.

Remarks

• Worklet runtimes come with performance.now and console.* methods installed out-of-the-box. Other APIs are not available and need to be injected into the runtime or captured via worklet closure.

• In development mode, all unhandled errors thrown in the runtime (except for those thrown in initializer) will be caught and thus logged to the console and displayed in a LogBox.

Platform compatibility

Native	Web
✅	❌