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

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## Unreleased
+
+Nothing has been published yet. This section becomes the first release entry.
+
+### Added
+
+- QuickJS as a React Native JavaScript engine, compiled from source in the app
+  build on Android and iOS. The engine is [quickjs-ng][ng], pre-patched with the
+  six changes described in `engine/patches/README.md`.
+- `npx react-native-quickjs install`, plus `revert` and `doctor`, and an Expo
+  config plugin for `npx expo prebuild`.
+- Release bundles compile to QuickJS bytecode on both platforms.
+- Chrome DevTools debugging: breakpoints, stepping, the call stack, variable
+  inspection and expression evaluation.
+- A Hermes compatibility shim, so libraries that link against Hermes -- most
+  importantly `react-native-worklets`, and through it `react-native-reanimated`
+  -- run unmodified. It is built only for an app that has left Hermes.
+- `TextEncoder` and `TextDecoder`, as `@react-native-quickjs/text-encoding`,
+  a dependency of this package so every app has them.
+
+### Known limitations
+
+- iOS compiles React Native core from source: removing Hermes removes the JSI
+  implementation that ships inside `hermesvm.framework`.
+- Conditional breakpoints stop unconditionally; the condition is stored and
+  reported but never evaluated.
+- React Native's non-Hermes path is patched at `pod install`. Each workaround
+  fails with a named error if React Native changes.
+- Expo's `getDefaultReactHost` hardcodes Hermes, so the config plugin edits
+  `node_modules`. Until [expo#PENDING][expo-pr] lands, an `npm install` reverts
+  that edit and the app silently launches on Hermes.
+
+[ng]: https://github.com/quickjs-ng/quickjs
+[expo-pr]: https://github.com/expo/expo/pulls

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 React Native QuickJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,31 @@
+@react-native-quickjs/quickjs
+Copyright (c) 2026 React Native QuickJS
+
+This product includes software developed by third parties, listed below. The
+license for this project is in LICENSE.
+
+--------------------------------------------------------------------------------
+QuickJS-NG
+https://github.com/quickjs-ng/quickjs
+
+The JavaScript engine. Its sources are redistributed in this package under
+engine/quickjs-rel, pre-patched with the changes in engine/patches -- each of
+which is described in engine/patches/README.md.
+
+  Copyright (c) 2016-2026 Fabrice Bellard
+  Copyright (c) 2017-2025 Charlie Gordon
+  Copyright (c) 2023-2026 Ben Noordhuis
+  Copyright (c) 2023-2026 Saúl Ibarra Corretgé
+  Copyright (c) 2023 Marcin Kolny
+
+Licensed under the MIT License.
+
+--------------------------------------------------------------------------------
+React Native (JSI)
+
+This package compiles React Native's own copy of JSI rather than vendoring one,
+so no JSI source is redistributed here. JSI is part of React Native.
+
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Licensed under the MIT License.

package/README.md

@@ -0,0 +1,217 @@
+<!-- GitHub strips <style> from SVG in Markdown, so the animated banner would
+     render as a still here anyway — this points at the PNG. The SVG in
+     docs/public/banner.svg is the source of truth and animates everywhere
+     else. -->
+<p align="center">
+  <img src=".github/assets/banner.png"
+       alt="react-native-quickjs"
+       width="880">
+</p>
+
+<h1 align="center">react-native-quickjs</h1>
+
+<p align="center">
+  A <a href="https://github.com/quickjs-ng/quickjs">QuickJS</a> JSI runtime for
+  React Native, compiled from source in every app.
+</p>
+
+Provides a `jsi::Runtime` backed by quickjs-ng, and the `JSRuntimeFactory` glue
+React Native uses to select it. The engine is compiled from source as part of
+the app build. Neither Hermes nor JavaScriptCore is linked into the result.
+
+> **Alpha.** See [Known limitations](#known-limitations). Breaking changes are
+> expected.
+
+## Requirements
+
+- React Native **0.85 or newer**, New Architecture enabled
+- iOS 15.1+ · Android 7.0+ (API 24)
+
+## Install
+
+```sh
+npm install @react-native-quickjs/quickjs@alpha
+npx react-native-quickjs install
+cd ios && pod install
+```
+
+For Expo, add the config plugin instead and run `expo prebuild`:
+
+```json
+{ "expo": { "plugins": ["@react-native-quickjs/quickjs"] } }
+```
+
+`npx react-native-quickjs doctor` reports which parts are configured, and
+`revert` puts the app back on Hermes.
+
+The two sections below are the changes `install` makes. Follow them by hand if
+you would rather, or if `install` reports a file it could not edit.
+
+## iOS
+
+**1. Podfile**
+
+```ruby
+require_relative '../node_modules/@react-native-quickjs/quickjs/scripts/react_native_quickjs_pods.rb'
+
+target 'YourApp' do
+  config = use_native_modules!
+
+  use_quickjs!                       # must precede use_react_native!
+
+  use_react_native!(:path => config[:reactNativePath])
+
+  post_install do |installer|
+    react_native_post_install(installer, config[:reactNativePath])
+    react_native_quickjs_post_install(installer)   # must follow it
+  end
+end
+```
+
+`use_quickjs!` removes Hermes from the pod graph.
+`react_native_quickjs_post_install` sets `USE_HERMES=false`, which stops release
+builds compiling the bundle to Hermes bytecode.
+
+**2. AppDelegate.swift**
+
+```swift
+import ReactNativeQuickJS
+
+class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
+  override func createJSRuntimeFactory() -> JSRuntimeFactoryRef {
+    jsrt_create_quickjs_factory()
+  }
+}
+```
+
+Then run `pod install`.
+
+## Android
+
+**1. `android/gradle.properties`**
+
+```properties
+hermesEnabled=false
+```
+
+**2. `android/app/build.gradle`** — remove the engine selection block:
+
+```diff
+ dependencies {
+     implementation("com.facebook.react:react-android")
+-
+-    if (hermesEnabled.toBoolean()) {
+-        implementation("com.facebook.react:hermes-android")
+-    } else {
+-        implementation jscFlavor
+-    }
+ }
+```
+
+`libjsc.so` is about 10 MB per architecture. The build warns if either
+dependency is still declared.
+
+**3. `android/app/build.gradle`** — apply the Gradle script, as the last line:
+
+```groovy
+apply from: file("../../node_modules/@react-native-quickjs/quickjs/android/quickjs.gradle")
+```
+
+React Native strips the engine the app is not using, and with only two engines
+to choose from it reads "not Hermes" as "delete `libhermesvm.so`" — the name the
+Hermes compatibility shim has to carry for `react-native-worklets` to find it.
+This script does the same removals, minus that one file, and fails the build if
+a real Hermes ever reaches packaging.
+
+**4. `MainApplication.kt`**
+
+```kotlin
+import com.reactnativequickjs.quickjs.QuickJSInstance
+
+override val reactHost: ReactHost by lazy {
+  getDefaultReactHost(
+    context = applicationContext,
+    packageList = PackageList(this).packages,
+    jsRuntimeFactory = QuickJSInstance(),
+  )
+}
+```
+
+## Debugging
+
+Chrome DevTools attaches over React Native's inspector: breakpoints, stepping,
+call stacks, scope inspection and console. The backend is compiled into debug
+builds and omitted from release builds.
+
+## Bytecode bundles
+
+Release builds compile the JavaScript bundle to QuickJS bytecode, which is what
+the app then loads. Debug builds are untouched -- they load JavaScript from
+Metro. There is nothing to configure.
+
+The compiler is pinned to the engine by `BC_VERSION`, because bytecode is only
+loadable by the engine build that produced it. If the two ever disagree the
+build stops rather than shipping a bundle the app cannot read.
+
+Set `RNQJS_BYTECODE=0` (iOS) or `-PrnqjsBytecode=false` (Android) to ship plain
+JavaScript instead.
+
+## Hermes compatibility
+
+Many React Native libraries create their own JavaScript runtime by calling into
+Hermes directly -- `react-native-worklets` does, and so `react-native-reanimated`
+does through it. They include `<hermes/hermes.h>` and link the Hermes library by
+name, neither of which exists in a QuickJS app.
+
+A compatibility shim ships that header and library, backed by this engine, so
+those libraries build and run unmodified. `makeHermesRuntime()` returns a QuickJS
+runtime; on Android the library is named `libhermesvm.so`, which is the name they
+look for. It is about 100 KB and contains no second engine.
+
+This is on by default. `RNQJS_HERMES_COMPAT=0` (iOS) or `-PrnqjsHermesCompat=false`
+(Android) turns it off, which is worth doing only if nothing in the app wants
+Hermes: with it on, any library that feature-detects `__has_include(<hermes/hermes.h>)`
+takes its Hermes path, and gets this engine.
+
+The shim covers the whole public Hermes API. Calls that have no QuickJS meaning
+return sensible values rather than failing, and report themselves once through
+`hermes-compat/Diagnostics.h`.
+
+## Known limitations
+
+| | |
+|---|---|
+| **iOS compiles React Native core from source** | `use_quickjs!` sets `RCT_USE_PREBUILT_RNCORE=0`. On the prebuilt path `hermesvm.framework` also carries the JSI implementation, so removing Hermes removes JSI with it. First builds and cold CI are slower. |
+| **Conditional breakpoints always stop** | A breakpoint `condition` is stored and reported back, never evaluated. |
+| **React Native is patched at `pod install`** | `scripts/react_native_quickjs_pods.rb` applies five workarounds to React Native 0.85's non-Hermes path. Each fails with a named error if React Native changes. |
+
+## Building this repository
+
+```sh
+git clone --recurse-submodules https://github.com/react-native-quickjs/quickjs
+cd quickjs && npm install
+npm test          # configures, builds, and runs the suites
+```
+
+| Path | What it is |
+| --- | --- |
+| `src/` | The `jsi::Runtime` implementation, shared by both platforms. |
+| `android/` | Gradle module, CMake build, fbjni hybrid, and `QuickJSInstance.kt`. |
+| `apple/` | `jsrt_create_quickjs_factory()`, the iOS entry point. |
+| `engine/quickjs-ng/` | quickjs-ng, as a pinned git submodule. |
+| `engine/patches/` | The engine patches applied to it. See [its README](engine/patches/README.md). |
+| `engine/quickjs-rel/` | Generated: the submodule with the patches applied. This is what ships. |
+| `modules/cdp/` | The Chrome DevTools Protocol backend, in C. See [its README](modules/cdp/README.md). |
+| `cmake/quickjs.cmake` | The quickjs target, shared by the Android and host builds. |
+| `tools/bytecode/` | `qjsc`, the ahead-of-time bytecode compiler. |
+| `tests/` | Host suites, Hermes' JSI conformance suite, and the differential corpus. |
+| `example/` | An app that runs on QuickJS, used as the end-to-end check. |
+| `docs/` | The landing page. |
+
+`engine/quickjs-rel` is generated, never hand-edited. The build fails if it
+disagrees with the submodule plus the patches.
+
+## License
+
+MIT. QuickJS-ng is MIT, © Fabrice Bellard, Charlie Gordon and the quickjs-ng
+contributors.

package/ReactNativeQuickJS.podspec

@@ -0,0 +1,197 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# The engine compiled here is engine/quickjs-rel: the committed, pre-patched
+# projection of the engine/quickjs-ng submodule, generated by
+# scripts/sync-quickjs-rel.js. The submodule cannot be what ships -- our patches
+# live in its working tree, which `git submodule update` reverts, and npm does
+# not pack submodules at all.
+#
+# One existence check remains, because a wrong `files` entry in package.json
+# still produces a tarball without these sources, and a missing-source failure
+# at `pod install` is far cheaper to read than the hundreds of compiler errors
+# it becomes otherwise.
+quickjs_dir = File.join(__dir__, "engine", "quickjs-rel")
+unless File.exist?(File.join(quickjs_dir, "quickjs.c"))
+  raise "[ReactNativeQuickJS] engine/quickjs-rel is missing. Run: node scripts/sync-quickjs-rel.js"
+end
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeQuickJS"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => package["repository"]["url"], :tag => "v#{s.version}" }
+
+  # engine/quickjs-rel contains only these files -- the sync script derives the
+  # list from the #include closure and deletes anything else -- so the globs
+  # cannot pick up a stray main() the way they could against the full submodule.
+  s.source_files = [
+    "apple/*.{h,mm}",
+    "src/**/*.{h,cpp}",
+    # The Chrome DevTools Protocol backend. quickjs-cdp.c needs only
+    # <quickjs.h>; react/ needs jsinspector-modern and folly, which the
+    # React-jsinspector dependency below provides.
+    "modules/cdp/*.{h,c}",
+    "modules/cdp/react/*.{h,cpp}",
+    "engine/quickjs-rel/*.h",
+    # libregexp.c #includes libregexp-backtrack.c.inc twice, to build the 8-bit
+    # and 16-bit matchers, so the .inc has to be copied too.
+    "engine/quickjs-rel/*.inc",
+    "engine/quickjs-rel/quickjs.c",
+    "engine/quickjs-rel/libregexp.c",
+    "engine/quickjs-rel/libunicode.c",
+    "engine/quickjs-rel/dtoa.c",
+  ]
+
+  # Consumers only ever need the C factory entry point.
+  s.public_header_files = "apple/RCTQuickJSInstanceFactory.h"
+
+  # DEFINES_MODULE makes CocoaPods emit a module map even though this builds as
+  # a static library, which is what lets an app's AppDelegate.swift write
+  # `import ReactNativeQuickJS`.
+  s.module_name = "ReactNativeQuickJS"
+
+  # Expo's ExpoModulesJSI is a prebuilt dynamic framework that resolves JSI from
+  # the flat namespace when it loads. Two of the symbols it needs come from
+  # React-jsi and nothing linked statically into the app refers to them, so the
+  # linker drops both and dyld kills the app before main() with
+  # "symbol not found in flat namespace '__ZTIN8facebook3jsi13MutableBufferE'".
+  #
+  # Both are named, not just the destructor: ld64 dead-strips per atom rather
+  # than per object file, so keeping the destructor does not keep the typeinfo
+  # sitting beside it in the same object.
+  #
+  # Plain React Native never loads JSI dynamically and does not need this; there
+  # it retains two symbols nothing asks for.
+  s.user_target_xcconfig = {
+    "OTHER_LDFLAGS" => "$(inherited) " \
+      "-Wl,-u,__ZN8facebook3jsi13MutableBufferD2Ev " \
+      "-Wl,-u,__ZTIN8facebook3jsi13MutableBufferE"
+  }
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    # The interpreter recurses on the native stack: one JavaScript call is one
+    # JS_CallInternal frame. Unoptimized that frame is around 10 KB, so on
+    # React Native's JavaScript thread only about 80 JavaScript calls fit --
+    # too few for React to render, and a Debug app comes up blank or reports
+    # "Maximum call stack size exceeded" from whichever library recurses first.
+    #
+    # Debug only: Release already optimizes, and forcing a level there would
+    # override the -Os the rest of the pods are built with. This covers the
+    # whole pod rather than the engine alone, which CocoaPods gives no way to
+    # single out, so the JSI layer is optimized in a Debug app too -- this
+    # project's own debugging is done through the host CMake build, which is
+    # left unoptimized.
+    "GCC_OPTIMIZATION_LEVEL[config=Debug]" => "2",
+    # Must be quickjs-rel and not quickjs-ng. Pointing this at the submodule
+    # while compiling the -rel sources would take headers from one copy and
+    # translation units from the other: fine while they agree, and a
+    # struct-layout mismatch with no diagnostic the moment they do not.
+    "HEADER_SEARCH_PATHS" =>
+      "\"$(PODS_TARGET_SRCROOT)/src/bytecode\" " \
+      "\"$(PODS_TARGET_SRCROOT)/src/module\" " \
+      "\"$(PODS_TARGET_SRCROOT)/src/runtime\" " \
+      "\"$(PODS_TARGET_SRCROOT)/engine/quickjs-rel\" " \
+      "\"$(PODS_TARGET_SRCROOT)/modules/cdp\" " \
+      "\"$(PODS_TARGET_SRCROOT)/modules/cdp/react\"",
+    "GCC_C_LANGUAGE_STANDARD" => "gnu11",
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    # JS_ENABLE_DEBUGGER must agree with cmake/quickjs.cmake, which defaults it
+    # on for the host and Android builds. quickjs.h declares the debugger entry
+    # points either way, so a build that compiles them out fails at link rather
+    # than at the call site.
+    #
+    # RNQJS_ENABLE_CDP is absent on purpose: undefined means no DevTools
+    # backend, and react_native_quickjs_post_install defines it for debug only.
+    "GCC_PREPROCESSOR_DEFINITIONS" =>
+      "$(inherited) _GNU_SOURCE=1 JS_ENABLE_DEBUGGER=1",
+    "USE_HEADERMAP" => "YES",
+  }
+
+  # quickjs builds warning-clean upstream, but not under React Native's flags.
+  s.compiler_flags = "-Wno-unused-parameter -Wno-unused-variable -Wno-sign-compare -Wno-implicit-fallthrough"
+
+  # The Hermes compatibility shim, opt-in.
+  #
+  # modules/hermes-compat publishes a source-compatible <hermes/hermes.h> whose
+  # makeHermesRuntime() returns a QuickJS-backed runtime, so react-native-worklets
+  # -- and so react-native-reanimated -- build and run unmodified.
+  #
+  # On by default: react-native-worklets does not build without it, and neither
+  # does react-native-reanimated, which is most apps. RNQJS_HERMES_COMPAT=0 in
+  # the Podfile turns it off.
+  #
+  # react_native_quickjs_post_install puts these headers on every pod's header
+  # search path, so any library feature-detecting with
+  # __has_include(<hermes/hermes.h>) believes this is a Hermes app -- which is
+  # the point: what it then calls is this engine.
+  hermes_compat = ENV["RNQJS_HERMES_COMPAT"] != "0"
+
+  # The shim is source-compatible with Hermes, not ABI-compatible. With the
+  # hermes-engine pod also installed the target has two <hermes/hermes.h> on one
+  # search path and two definitions of makeHermesRuntime on one link line, and
+  # pod ordering decides which wins. use_hermes() is what decides whether that
+  # pod is there, so ask it rather than reading ENV["USE_HERMES"]: React Native
+  # sets that pod up from use_hermes(), which never consults that variable.
+  #
+  # Skipped rather than raised. Now that the shim is on by default this is
+  # reached by installing the package and running pod install before
+  # `npx react-native-quickjs install` has edited the Podfile -- a normal step
+  # in setting the package up, and no place to abort.
+  if hermes_compat && defined?(use_hermes) && use_hermes()
+    Pod::UI.warn(
+      "[ReactNativeQuickJS] the Hermes compatibility shim was skipped because " \
+      "the hermes-engine pod is installed. Add use_quickjs! to the Podfile " \
+      "(`npx react-native-quickjs install` does it) and run pod install again."
+    )
+    hermes_compat = false
+  end
+
+  if hermes_compat
+    s.subspec "HermesCompat" do |ss|
+      ss.source_files = [
+        "modules/hermes-compat/src/*.cpp",
+        "modules/hermes-compat/include/**/*.h",
+      ]
+
+      # Private on purpose. This pod sets DEFINES_MODULE, so a public header
+      # joins ReactNativeQuickJS-umbrella.h, which Clang compiles as Objective-C
+      # while building the module -- and <hermes/hermes.h> reaches <cstdint>,
+      # which that compile cannot resolve. CocoaPods would also install them
+      # under Headers/Public/ReactNativeQuickJS/hermes/, so <hermes/hermes.h>
+      # would not resolve for a consumer either.
+      #
+      # react_native_quickjs_post_install puts the source directory itself on
+      # every pod's header search path instead, which is what worklets needs.
+      ss.private_header_files = "modules/hermes-compat/include/**/*.h"
+
+      ss.pod_target_xcconfig = {
+        # Our own sources include <hermes/hermes.h> and
+        # <hermes-compat/Diagnostics.h> from the source tree.
+        "HEADER_SEARCH_PATHS" =>
+          "$(inherited) \"$(PODS_TARGET_SRCROOT)/modules/hermes-compat/include\"",
+        # Unconditional, not tied to the configuration: RNWorklets.podspec sets
+        # HERMES_ENABLE_DEBUGGER=1 for every Debug build regardless of
+        # USE_HERMES, so a Debug worklets references enableDebugging and needs
+        # it defined. Safe only because no member declaration in the shim's
+        # headers is conditional on this macro.
+        "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) HERMES_ENABLE_DEBUGGER=1",
+      }
+    end
+  end
+
+  install_modules_dependencies(s)
+
+  s.dependency "React-jsi"
+  s.dependency "React-cxxreact"
+  s.dependency "React-RuntimeCore"
+  add_dependency(s, "React-jsitooling", :framework_name => "JSITooling")
+  add_dependency(s, "React-jsinspector", :framework_name => "jsinspector_modern")
+end

package/android/CMakeLists.txt

@@ -0,0 +1,134 @@
+# 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.
+#
+# Builds libquickjsinstancejni.so, the shared library the Kotlin QuickJSInstance
+# loads. Driven by build.gradle, never configured directly.
+
+cmake_minimum_required(VERSION 3.20)
+project(quickjsinstancejni CXX C)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if(NOT DEFINED REACT_NATIVE_DIR)
+  message(FATAL_ERROR "REACT_NATIVE_DIR must be passed in from build.gradle")
+endif()
+
+set(RNQJS_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/..")
+
+# React Native's headers reach into folly, which does not compile without these
+# flags unless a generated folly-config.h is on the include path.
+include("${REACT_NATIVE_DIR}/ReactAndroid/cmake-utils/folly-flags.cmake")
+add_compile_options(${folly_FLAGS})
+
+include("${RNQJS_ROOT}/cmake/quickjs.cmake")
+
+# Every src/ translation unit has to be listed. The Apple build globs src/,
+# so a file added there builds on iOS and fails to link on Android -- an
+# asymmetry worth remembering when adding a source.
+add_library(quickjsinstancejni SHARED
+  "${RNQJS_ROOT}/src/bytecode/QuickJSBytecode.cpp"
+  "${RNQJS_ROOT}/src/module/QuickJSCompat.cpp"
+  "${RNQJS_ROOT}/src/module/QuickJSModule.cpp"
+  "${RNQJS_ROOT}/src/runtime/QuickJSInstance.cpp"
+  "${RNQJS_ROOT}/src/runtime/QuickJSRuntime.cpp"
+  "${RNQJS_ROOT}/src/runtime/QuickJSRuntimeFactory.cpp"
+  src/main/jni/JQuickJSInstance.cpp
+  src/main/jni/OnLoad.cpp
+)
+
+target_include_directories(quickjsinstancejni PRIVATE
+  "${RNQJS_ROOT}/src/bytecode"
+  "${RNQJS_ROOT}/src/module"
+  "${RNQJS_ROOT}/src/runtime"
+  "${CMAKE_CURRENT_SOURCE_DIR}/src/main/jni"
+)
+
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+target_link_libraries(quickjsinstancejni
+  quickjs
+  fbjni::fbjni
+  ReactAndroid::jsi
+  ReactAndroid::reactnative
+  android
+  log
+)
+
+# --- Chrome DevTools Protocol ----------------------------------------------
+#
+# In debug builds, out of release builds, which is what
+# QuickJSInstance::debuggerEnabledByDefault() already decides at runtime.
+# -DRNQJS_ENABLE_CDP=ON puts it back.
+#
+# The two sources are compiled here rather than through modules/cdp's own
+# CMakeLists because that file also declares a host test target. Two files is
+# less machinery than teaching it to be cross-compiled.
+if(CMAKE_BUILD_TYPE MATCHES Debug)
+  set(RNQJS_CDP_DEFAULT ON)
+else()
+  set(RNQJS_CDP_DEFAULT OFF)
+endif()
+option(RNQJS_ENABLE_CDP "Compile in the Chrome DevTools Protocol backend"
+       ${RNQJS_CDP_DEFAULT})
+
+if(RNQJS_ENABLE_CDP)
+  set(CDP_DIR "${RNQJS_ROOT}/modules/cdp")
+  target_sources(quickjsinstancejni PRIVATE
+    "${CDP_DIR}/quickjs-cdp.c"
+    "${CDP_DIR}/react/QuickJSInspector.cpp"
+  )
+  target_include_directories(quickjsinstancejni PRIVATE
+    "${CDP_DIR}" "${CDP_DIR}/react")
+  target_compile_definitions(quickjsinstancejni PRIVATE RNQJS_ENABLE_CDP=1)
+endif()
+
+# The Hermes compatibility shim, opt-in, built as libhermesvm.so.
+#
+# react-native-worklets picks its engine at compile time and links React
+# Native's imported `hermes` target, so what it records as NEEDED is the file
+# that target points at. On React Native 0.85 that is libhermesvm.so, not
+# libhermes.so -- see ReactAndroid/src/main/jni/first-party/hermes/CMakeLists.txt.
+# Giving it a library of that name, whose makeHermesRuntime returns a QuickJS
+# runtime, is what lets it run here unmodified.
+#
+# It links libquickjsinstancejni.so rather than compiling the engine again:
+# two copies would mean two engines in one app, and roughly a megabyte of
+# duplicate code per architecture.
+#
+# On by default: react-native-worklets does not load without it, and neither
+# does react-native-reanimated, which is most apps. -PrnqjsHermesCompat=false
+# turns it off.
+option(RNQJS_HERMES_COMPAT "Build the Hermes compatibility shim as libhermesvm.so" ON)
+if(RNQJS_HERMES_COMPAT)
+  add_library(hermes SHARED
+    "${RNQJS_ROOT}/modules/hermes-compat/src/HermesCompat.cpp")
+
+  target_include_directories(hermes PUBLIC
+    "${RNQJS_ROOT}/modules/hermes-compat/include")
+  target_include_directories(hermes PRIVATE
+    "${RNQJS_ROOT}/src/bytecode"
+    "${RNQJS_ROOT}/src/module"
+    "${RNQJS_ROOT}/src/runtime")
+
+  # Unconditional, matching the podspec: RNWorklets defines this for every
+  # Debug build, so enableDebugging must exist whatever this library was
+  # compiled with. Safe only because no member declaration in the shim's
+  # headers is conditional on it.
+  target_compile_definitions(hermes PRIVATE HERMES_ENABLE_DEBUGGER=1)
+
+  target_link_libraries(hermes
+    quickjsinstancejni
+    ReactAndroid::jsi
+    android
+    log
+  )
+
+  set_target_properties(hermes PROPERTIES
+    OUTPUT_NAME hermesvm
+    POSITION_INDEPENDENT_CODE ON
+  )
+endif()