feat(Worklets): allow passing user-implemented AsyncQueue to createWorkletRuntime

[tjzel]

Summary

As requested in #7831. I opted to use jsi::NativeState instead of jsi::HostObject since it introduces less boilerplate.

Test plan

diff --git a/apps/common-app/src/apps/reanimated/examples/EmptyExample.tsx b/apps/common-app/src/apps/reanimated/examples/EmptyExample.tsx
index 7f3a1ac26c..6e476f11ea 100644
--- a/apps/common-app/src/apps/reanimated/examples/EmptyExample.tsx
+++ b/apps/common-app/src/apps/reanimated/examples/EmptyExample.tsx
@@ -1,10 +1,33 @@
 import React from 'react';
-import { StyleSheet, Text, View } from 'react-native';
+import { Button, StyleSheet, Text, View } from 'react-native';
+import { createWorkletRuntime, runOnRuntime } from 'react-native-worklets';
 
 export default function EmptyExample() {
   return (
     <View style={styles.container}>
       <Text>Hello world!</Text>
+      <Button
+        title="Create Worklet Runtime"
+        onPress={() => {
+          const asyncQueue = globalThis._WORKLETS_ASYNC_QUEUE;
+          console.log(asyncQueue, 'Async Queue');
+          const workletRuntime = createWorkletRuntime(
+            'EmptyExample',
+            () => {
+              'worklet';
+            },
+            asyncQueue
+          );
+          console.log(workletRuntime, 'Worklet Runtime');
+          runOnRuntime(workletRuntime, () => {
+            'worklet';
+            console.log(
+              'Worklet Runtime created successfully!',
+              globalThis._LABEL
+            );
+          })();
+        }}
+      />
     </View>
   );
 }
diff --git a/packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RNRuntimeWorkletDecorator.cpp b/packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RNRuntimeWorkletDecorator.cpp
index afaac36a40..7864a9a7c7 100644
--- a/packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RNRuntimeWorkletDecorator.cpp
+++ b/packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RNRuntimeWorkletDecorator.cpp
@@ -1,3 +1,4 @@
+#include <worklets/Tools/AsyncQueue.h>
 #include <worklets/Tools/WorkletsVersion.h>
 #include <worklets/WorkletRuntime/RNRuntimeWorkletDecorator.h>
 #include <worklets/WorkletRuntime/WorkletRuntimeCollector.h>
@@ -20,6 +21,16 @@ void RNRuntimeWorkletDecorator::decorate(
   rnRuntime.global().setProperty(
       rnRuntime, "__workletsModuleProxy", std::move(jsiWorkletsModuleProxy));
 
+  auto asyncQueue = std::make_shared<AsyncQueueImpl>("TestRuntimeAsyncQueue");
+
+  auto obj = jsi::Object(rnRuntime);
+
+  obj.setNativeState(
+      rnRuntime, std::static_pointer_cast<jsi::NativeState>(asyncQueue));
+
+  rnRuntime.global().setProperty(
+      rnRuntime, "_WORKLETS_ASYNC_QUEUE", std::move(obj));
+
   WorkletRuntimeCollector::install(rnRuntime);
 
 #ifndef NDEBUG

[mrousavy]

Beat me to it! Wanted to draft something up today but couldn't find the time.

I'll test this tmrw, thanks so much! :)

[mrousavy]

oh btw., we would still need support for capturing NativeState properly.

const myObj = ...
function worklet() {
  'worklet'
  myObj.myFunc()
}

myObj is an empty jsi::Object (or sometimes it contains some values) with jsi::NativeState - and myFunc() expects it's this to be bound to the myObj (which contains the NativeState).

Then it'd be ready for a VisionCamera prototype

[tjzel]

Could you elaborate on that? I'm not sure I get it, since you said that myObj is empty but then you invoke myFunc() on it. Is myFunc() a host function?

[mrousavy]

Yes myFunc is a HostFunction that needs this bound.

[tjzel]

Could you give me a link to the place in the code when you use this pattern? I think I need to understand what's going on to implement that.

[mrousavy]

This is how a function on a Nitro HybridObject looks like.

It's a jsi::HostFunction, which uses the const jsi::Value& thisValue (second argument in a jsi::HostFunction) to get the bound this value of the function - which, if you call it from JS like this;

myObj.myFunc()

..will be myObj. myObj is then the jsi::Object that contains jsi::NativeState.

So for Worklets what needs to be done to properly keep this functionality;

• capture myObj as a normal jsi::Object as usual, and copy any values if it has some (e.g. in debug it has a __type: string property), and most importantly; copy over the std::shared_ptr<jsi::NativeState> it contains.

[mrousavy]

The simplest way to test this is;

• Install react-native-nitro-modules into REA example app
• In native C++, create a HybridObject;

  using namespace margelo::nitro;
  
  class HybridTestObject: public HybridObject {
  public:
    HybridTestObject(): HybridObject(NAME) { }
    static constexpr auto NAME = "TestObject";
  
  public:
    void hello() {
      std::cout << "It works!" << std::endl;
    }
  
  protected:
    void loadHybridMethods() override {
      HybridObject::loadHybridMethods();
      registerHybrids(this, [](Prototype& proto) {
        proto.registerHybridMethod("hello", & HybridTestObject::hello);
      });
    }
  };

3. Create an instance of HybridTestObject, then get it to JS - if you already have a JS Runtime you can just call:

   auto hybrid = std::make_shared<HybridTestObject>();
   jsi::Value object = hybrid->toObject(runtime);
   runtime.global().setProperty(runtime, "testObject", std::move(object));

..or just install a Nitro Module like e.g. react-native-unistyles, react-native-nitro-image, react-native-video v7, ...

EDIT: Btw the most efficient way of capturing Nitro HybridObjects would be if you guys would actually call the toObject(runtime) function on the HybridObject. This is cached (jsi::WeakObject per runtime) and super fast. But it would require you to do a #if __has_include(<NitroModules/HybridObject.hpp>) - not sure if you guys want to do that.

[tjzel]

I think this is already supported right off the bat, but let me double check it 🙏

[tjzel]

Yep, I tested it - HostFunction & this and the native state work already. Regarding the #ifdef, I don't mind putting it in the code if it's going to be non-invasive.

[mrousavy]

awesome!

[Copilot]

Pull Request Overview

This PR adds support for passing user-implemented AsyncQueue objects to the createWorkletRuntime function, fulfilling a feature request from issue #7831. The implementation uses jsi::NativeState to avoid boilerplate and provides backward compatibility through function overloads.

• Enhanced createWorkletRuntime to accept optional custom AsyncQueue implementations
• Updated the type system with discriminated unions to ensure proper queue configuration
• Modified the C++ layer to handle custom queue injection through the JSI bridge

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/react-native-worklets/src/runtimes.ts	Added overloads and queue configuration options to createWorkletRuntime
packages/react-native-worklets/src/WorkletsModule/workletsModuleProxy.ts	Extended interface to include queue parameters
packages/react-native-worklets/src/WorkletsModule/NativeWorklets.ts	Updated implementation to pass queue parameters through
packages/react-native-worklets/src/WorkletsModule/JSWorklets.ts	Simplified JSWorklets implementation signature
packages/react-native-worklets/typetests/createWorkletRuntime.tsx	Added comprehensive type tests for new queue configuration options
packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/WorkletRuntime.h	Added queue parameter to constructor and runtime assertion
packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/WorkletRuntime.cpp	Updated constructor to accept and store custom queue
packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RuntimeManager.h	Extended createWorkletRuntime method signature
packages/react-native-worklets/Common/cpp/worklets/WorkletRuntime/RuntimeManager.cpp	Updated runtime creation to pass custom queue
packages/react-native-worklets/Common/cpp/worklets/NativeModules/JSIWorkletsModuleProxy.cpp	Added queue extraction logic and parameter handling

[tjzel]

@mrousavy We got it merged 🥳 It will be available in [email protected] soon™!

[mrousavy]

super cool!! thanks