@react-native-quickjs/quickjs 1.0.0-alpha.0

package/android/build.gradle

@@ -0,0 +1,214 @@
+buildscript {
+  ext.ReactNativeQuickJS = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return ReactNativeQuickJS[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+android {
+  namespace "com.reactnativequickjs.quickjs"
+
+  // Follow the app's NDK, or let the Android plugin choose. Pinning our own
+  // would compile this library with a different toolchain than the app.
+  if (rootProject.ext.has("ndkVersion")) {
+    ndkVersion rootProject.ext.get("ndkVersion")
+  }
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        // ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES gives the shared library 16 KB
+        // LOAD alignment. Without it we link at 4 KB while every prebuilt in
+        // the same APK -- libreactnative.so, libjsi.so, libfbjni.so,
+        // libc++_shared.so -- is already 16 KB, and on an Android 15 kernel
+        // the loader refuses ours outright:
+        //
+        //   "...so" program alignment (4096) cannot be smaller than
+        //    system page size (16384)
+        //
+        // The process is killed at System.loadLibrary, so there is no partial
+        // functionality to notice: the app does not start. NDK r27 leaves this
+        // off by default, r28 turns it on, and no host build can see it.
+        arguments "-DANDROID_STL=c++_shared",
+                  "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON",
+                  "-DREACT_NATIVE_DIR=${reactNativeDir()}"
+
+        // Left unset, CMakeLists.txt takes the DevTools backend from the build
+        // type. -PrnqjsEnableCdp=true|false forces it either way.
+        if (project.hasProperty('rnqjsEnableCdp')) {
+          def on = project.property('rnqjsEnableCdp').toString() != 'false'
+          arguments "-DRNQJS_ENABLE_CDP=${on ? 'ON' : 'OFF'}"
+        }
+
+        // Ships the Hermes compatibility shim as libhermesvm.so, so libraries
+        // that link against Hermes -- react-native-worklets, and so
+        // react-native-reanimated -- run on QuickJS unmodified.
+        arguments "-DRNQJS_HERMES_COMPAT=${hermesCompatEnabled() ? 'ON' : 'OFF'}"
+
+        abiFilters(*reactNativeArchitectures())
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+      version "3.22.1"
+    }
+  }
+
+  buildFeatures {
+    // Required to consume ReactAndroid::jsi and ReactAndroid::reactnative from
+    // the react-android AAR via find_package(ReactAndroid CONFIG).
+    prefab true
+  }
+
+  packagingOptions {
+    // These ship with React Native itself; a second copy would conflict at
+    // load time.
+    excludes += [
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libreactnative.so",
+    ]
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+// Whether to build the Hermes compatibility shim.
+//
+// Autolinking puts this library into every app that has the package installed,
+// including one still running Hermes and one part-way through switching over.
+// The shim is named libhermesvm.so, because that is the name the libraries
+// needing it look for, so building it in a Hermes app puts a second file of
+// that name into the merge -- and a ~100 KB shim winning over the real engine
+// leaves the app dead at startup with NoClassDefFoundError: HermesInstance.
+//
+// So it is built only once the app has actually left Hermes, which is what
+// hermesEnabled=false in gradle.properties says. -PrnqjsHermesCompat decides
+// it outright either way.
+def hermesCompatEnabled() {
+  if (project.hasProperty('rnqjsHermesCompat')) {
+    return project.property('rnqjsHermesCompat').toString() != 'false'
+  }
+  return rootProject.findProperty('hermesEnabled')?.toString() == 'false'
+}
+
+// Resolved through node so this works regardless of how the consuming app
+// hoists its node_modules.
+def reactNativeDir() {
+  def resolved = providers.exec {
+    workingDir(rootDir)
+    commandLine("node", "--print", "require.resolve('react-native/package.json')")
+  }.standardOutput.asText.get().trim()
+
+  return new File(resolved).getParentFile().getAbsolutePath()
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.facebook.fbjni:fbjni:0.7.0"
+}
+
+// The app template picks Hermes or JavaScriptCore in its own build.gradle, and
+// an app on QuickJS wants neither -- but hermesEnabled=false lands it in the
+// JavaScriptCore branch. Gradle gives a library no way to drop a dependency the
+// app itself declared, so warn instead.
+gradle.projectsEvaluated {
+  rootProject.subprojects.each { app ->
+    if (!app.plugins.hasPlugin("com.android.application")) return
+
+    def declared = app.configurations.findByName("implementation")
+        ?.dependencies?.collect { it.name } ?: []
+
+    if (declared.contains("hermes-android")) {
+      app.logger.warn("[ReactNativeQuickJS] ${app.path} bundles Hermes. Set " +
+          "hermesEnabled=false in gradle.properties, or a release bundle is " +
+          "Hermes bytecode that QuickJS cannot execute.")
+    }
+    if (declared.any { it.startsWith("jsc-android") }) {
+      app.logger.warn("[ReactNativeQuickJS] ${app.path} bundles JavaScriptCore " +
+          "and never loads it. Remove the jscFlavor dependency to save about " +
+          "10 MB per architecture.")
+    }
+  }
+}
+
+// Compile the release bundle to QuickJS bytecode, after React Native has
+// written it. Debug builds load JavaScript from Metro and never produce a
+// bundle, so there is nothing to compile. -PrnqjsBytecode=false turns it off.
+
+// ExecOperations is how a Gradle 9 build spawns a process; project.exec was
+// removed. A plain ProcessBuilder also runs, but not identically: under a
+// Volta-managed node it fails to resolve a version at all, in a build where
+// React Native's own bundle task -- which goes through ExecOperations -- had
+// just run the same binary.
+interface ReactNativeQuickJSProcess {
+  @javax.inject.Inject
+  org.gradle.process.ExecOperations getExecOperations()
+}
+
+gradle.projectsEvaluated {
+  if (project.findProperty('rnqjsBytecode')?.toString() == 'false') return
+
+  def compiler = file("${projectDir}/../scripts/bytecode/compile.js")
+
+  rootProject.subprojects.each { app ->
+    if (!app.plugins.hasPlugin("com.android.application")) return
+
+    def process = app.objects.newInstance(ReactNativeQuickJSProcess).execOperations
+    // The same node React Native bundles with, including an override of it.
+    def node = app.extensions.findByName('react')?.nodeExecutableAndArgs?.getOrNull() ?: ['node']
+
+    app.tasks.matching { it.name ==~ /createBundle.*JsAndAssets/ }.configureEach { bundleTask ->
+      bundleTask.doLast {
+        // Found by name rather than by reading the task's own properties,
+        // which are React Native Gradle plugin internals.
+        def assets = app.layout.buildDirectory.dir("generated/assets").get().asFile
+        app.fileTree(assets).matching { include '**/index.android.bundle' }.each { bundle ->
+          process.exec {
+            commandLine(*node, compiler.absolutePath, bundle.absolutePath)
+            workingDir app.rootDir
+          }
+        }
+      }
+    }
+  }
+}

package/android/quickjs.gradle

@@ -0,0 +1,39 @@
+// Copyright (c) Ammar Ahmed.
+//
+// This source code is licensed under the MIT license found in the
+// LICENSE file in the root directory of this source tree.
+//
+// Applied from the app's android/app/build.gradle:
+//
+//   apply from: file("../../node_modules/@react-native-quickjs/quickjs/android/quickjs.gradle")
+//
+// React Native strips the JavaScript engine the app is not using. It knows two
+// engines, so "not Hermes" means "delete **/libhermesvm.so" -- and that is the
+// name the Hermes compatibility shim has to carry, because it is what
+// react-native-worklets records as NEEDED. See useThirdPartyJSC in
+// NdkConfiguratorUtils.kt.
+//
+// Turning that cleanup off would also stop JavaScriptCore and the Hermes
+// tooling library being stripped, so it is replaced here rather than dropped:
+// the same removals, minus the one file this engine needs.
+
+react {
+  enableSoCleanup = false
+}
+
+androidComponents {
+  onVariants(selector().all()) { variant ->
+    variant.packaging.jniLibs.excludes.addAll([
+      "**/libjsc.so",
+      "**/libjsctooling.so",
+      "**/libhermestooling.so",
+    ])
+  }
+}
+
+// A transitively pulled Hermes would put a second libhermesvm.so into the merge
+// and the winner would be whichever the merger saw first -- a real engine,
+// satisfying worklets and starting up silently. So it cannot enter the graph.
+configurations.configureEach {
+  exclude group: "com.facebook.hermes", module: "hermes-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/reactnativequickjs/quickjs/QuickJSInstance.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+package com.reactnativequickjs.quickjs
+
+import com.facebook.jni.HybridData
+import com.facebook.jni.annotations.DoNotStrip
+import com.facebook.react.runtime.JSRuntimeFactory
+import com.facebook.soloader.SoLoader
+
+/**
+ * The QuickJS engine, as a drop-in replacement for
+ * `com.facebook.react.runtime.hermes.HermesInstance`.
+ *
+ * Pass it to `DefaultReactHost.getDefaultReactHost(...)` in your
+ * `MainApplication`:
+ * ```
+ * override val reactHost: ReactHost
+ *   get() = getDefaultReactHost(
+ *     applicationContext,
+ *     reactNativeHost,
+ *     jsRuntimeFactory = QuickJSInstance(),
+ *   )
+ * ```
+ */
+public class QuickJSInstance : JSRuntimeFactory(initHybrid()) {
+
+  public companion object {
+    @JvmStatic @DoNotStrip protected external fun initHybrid(): HybridData
+
+    init {
+      SoLoader.loadLibrary("quickjsinstancejni")
+    }
+  }
+}

package/android/src/main/java/com/reactnativequickjs/quickjs/QuickJSPackage.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+package com.reactnativequickjs.quickjs
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * Deliberately empty.
+ *
+ * This package exports no modules and no view managers -- QuickJS is wired in
+ * through [QuickJSInstance], not through the module system. It exists only
+ * because React Native's autolinking skips any Android library that does not
+ * expose a ReactPackage (see cli-config-android dependencyConfig), and without
+ * autolinking the gradle project is never included in the app build.
+ */
+public class QuickJSPackage : ReactPackage {
+  override fun createNativeModules(
+      reactContext: ReactApplicationContext
+  ): List<NativeModule> = emptyList()
+
+  override fun createViewManagers(
+      reactContext: ReactApplicationContext
+  ): List<ViewManager<*, *>> = emptyList()
+}

package/android/src/main/jni/JJSRuntimeFactory.h

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * ---------------------------------------------------------------------------
+ * Verbatim copy of
+ *   ReactAndroid/src/main/jni/react/runtime/jni/JJSRuntimeFactory.h
+ *
+ * React Native exports only ReactCommon/jsitooling through its prefab headers,
+ * so an out-of-tree engine has to carry its own copy of this one. It is a pure
+ * declaration -- it binds to the com.facebook.react.runtime.JSRuntimeFactory
+ * class that ships in the app -- so the copy duplicates no code, only a version
+ * coupling. Re-check it when raising the supported React Native version.
+ * ---------------------------------------------------------------------------
+ */
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include <jni.h>
+#include <react/runtime/JSRuntimeFactory.h>
+
+namespace facebook::react {
+
+class JJSRuntimeFactory : public jni::HybridClass<JJSRuntimeFactory>,
+                          public JSRuntimeFactory {
+ public:
+  static auto constexpr kJavaDescriptor =
+      "Lcom/facebook/react/runtime/JSRuntimeFactory;";
+
+ private:
+  friend HybridBase;
+};
+
+} // namespace facebook::react

package/android/src/main/jni/JQuickJSInstance.cpp

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "JQuickJSInstance.h"
+
+namespace facebook::react {
+
+jni::local_ref<JQuickJSInstance::jhybriddata> JQuickJSInstance::initHybrid(
+    jni::alias_ref<jclass>) {
+  return makeCxxInstance();
+}
+
+std::unique_ptr<JSRuntime> JQuickJSInstance::createJSRuntime(
+    std::shared_ptr<MessageQueueThread> msgQueueThread) noexcept {
+  return instance_.createJSRuntime(std::move(msgQueueThread));
+}
+
+void JQuickJSInstance::registerNatives() {
+  registerHybrid(
+      {makeNativeMethod("initHybrid", JQuickJSInstance::initHybrid)});
+}
+
+}  // namespace facebook::react

package/android/src/main/jni/JQuickJSInstance.h

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include <react/runtime/JSRuntimeFactory.h>
+
+#include <memory>
+
+#include "JJSRuntimeFactory.h"
+#include "QuickJSInstance.h"
+
+namespace facebook::react {
+
+class MessageQueueThread;
+
+/**
+ * The fbjni hybrid behind the Kotlin QuickJSInstance, mirroring React Native's
+ * own JHermesInstance: the Java-side object is a JSRuntimeFactory and the C++
+ * side answers createJSRuntime().
+ */
+class JQuickJSInstance
+    : public jni::HybridClass<JQuickJSInstance, JJSRuntimeFactory> {
+ public:
+  static constexpr auto kJavaDescriptor =
+      "Lcom/reactnativequickjs/quickjs/QuickJSInstance;";
+
+  static jni::local_ref<jhybriddata> initHybrid(jni::alias_ref<jclass>);
+
+  static void registerNatives();
+
+  std::unique_ptr<JSRuntime> createJSRuntime(
+      std::shared_ptr<MessageQueueThread> msgQueueThread) noexcept;
+
+ private:
+  friend HybridBase;
+
+  QuickJSInstance instance_;
+};
+
+}  // namespace facebook::react

package/android/src/main/jni/OnLoad.cpp

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include <fbjni/fbjni.h>
+
+#include "JQuickJSInstance.h"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void * /*reserved*/) {
+  return facebook::jni::initialize(
+      vm, [] { facebook::react::JQuickJSInstance::registerNatives(); });
+}

package/app.plugin.js

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Expo resolves a plugin referenced by package name to app.plugin.js at the
+ * package root.
+ */
+
+module.exports = require('./scripts/expo/plugin.js');

package/apple/RCTQuickJSInstanceFactory.h

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <react/runtime/JSRuntimeFactoryCAPI.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Creates the QuickJS engine factory, as a drop-in replacement for
+ * `jsrt_create_hermes_factory()`.
+ *
+ * Override `createJSRuntimeFactory` on your React Native factory delegate:
+ *
+ *   - (JSRuntimeFactoryRef)createJSRuntimeFactory
+ *   {
+ *     return jsrt_create_quickjs_factory();
+ *   }
+ *
+ * Ownership of the returned factory transfers to React Native, which releases
+ * it with `js_runtime_factory_destroy`.
+ */
+JSRuntimeFactoryRef jsrt_create_quickjs_factory(void);
+
+#ifdef __cplusplus
+}
+#endif

package/apple/RCTQuickJSInstanceFactory.mm

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "RCTQuickJSInstanceFactory.h"
+
+#import "QuickJSInstance.h"
+
+using namespace facebook::react;
+
+JSRuntimeFactoryRef jsrt_create_quickjs_factory(void) {
+  return reinterpret_cast<JSRuntimeFactoryRef>(new QuickJSInstance());
+}

package/bin/qjsc/manifest.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "Generated by .github/workflows/bytecode-compilers.yml. Do not edit.",
+  "bcVersion": 28,
+  "platforms": [
+    "darwin-arm64",
+    "darwin-x64",
+    "linux-arm64",
+    "linux-x64",
+    "win32-x64"
+  ]
+}

package/bin/react-native-quickjs.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const run = require('../scripts/setup/run.js');
+const [command, ...argv] = process.argv.slice(2);
+
+if (command in run) {
+  process.exit(run[command](argv));
+}
+
+console.log(`
+react-native-quickjs
+
+  install   configure this app to run on QuickJS
+  revert    configure it back to Hermes
+  doctor    report which parts are configured
+
+  --project <path>   act on this app instead of the current directory
+  --dry-run          show what would change, write nothing
+`);
+process.exit(command === undefined || command === '--help' || command === '-h' ? 0 : 1);

package/cmake/jsi.cmake

@@ -0,0 +1,24 @@
+# Copyright (c) Ammar Ahmed.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+# Defines the `jsi` static library.
+#
+# It compiles React Native's own copy of JSI, not a vendored one. jsi::Runtime
+# is abstract, so building against different headers than the app links is a
+# vtable mismatch: it compiles, links, and crashes at the first virtual call.
+
+set(REACT_NATIVE_DIR "${CMAKE_CURRENT_LIST_DIR}/../node_modules/react-native"
+    CACHE PATH "Path to the react-native package")
+set(JSI_DIR "${REACT_NATIVE_DIR}/ReactCommon/jsi")
+
+if(NOT EXISTS "${JSI_DIR}/jsi/jsi.cpp")
+  message(FATAL_ERROR
+    "Could not find JSI at ${JSI_DIR}.\n"
+    "Run `npm install` first, or pass -DREACT_NATIVE_DIR=/path/to/react-native")
+endif()
+
+add_library(jsi STATIC "${JSI_DIR}/jsi/jsi.cpp")
+target_include_directories(jsi PUBLIC "${JSI_DIR}")
+set_target_properties(jsi PROPERTIES POSITION_INDEPENDENT_CODE ON)