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

package/CHANGELOG.md

@@ -29,8 +29,8 @@ Nothing has been published yet. This section becomes the first release entry.
 - 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
+  `node_modules`. Until [expo#49686][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
+[expo-pr]: https://github.com/expo/expo/pull/49686

package/README.md

@@ -15,6 +15,14 @@
   React Native, compiled from source in every app.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@react-native-quickjs/quickjs"><img
+     alt="@react-native-quickjs/quickjs on npm"
+     src="https://img.shields.io/npm/v/@react-native-quickjs/quickjs/alpha?color=cb3837"></a>
+  <a href="LICENSE"><img alt="MIT licensed"
+     src="https://img.shields.io/badge/license-MIT-blue"></a>
+</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.

package/android/CMakeLists.txt

@@ -25,10 +25,60 @@ 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
+# Before any module subdirectory is configured: each module's CMakeLists probes
+# for ReactAndroid::jsi to decide whether to compile its JSI registration edge.
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+# Autolinked modules (@react-native-quickjs/* declaring reactNativeQuickJSModule,
+# listed by build.gradle) are folded into this .so: whole-archive so each
+# module's QJS_REGISTER_MODULE static initializer runs at load and its exported
+# Java_<module>_nativeAttach survives the link. RNQJS_QUICKJS_FOLDED tells a
+# module's platform JNI to skip JNI_OnLoad (one per .so) and capture the JavaVM
+# from its attach call instead. A module must not ship its own .so -- it would
+# load before the engine and fail to resolve the JS_* API.
+if(DEFINED RNQJS_QUICKJS_MODULES)
+  set(REACT_NATIVE_QUICKJS_DIR "${RNQJS_ROOT}" CACHE PATH "" FORCE)
+  add_compile_definitions(RNQJS_QUICKJS_FOLDED=1)
+
+  set(RNQJS_FOLDED_TARGETS "")
+  set(RNQJS_REGISTRY_DIRS "")
+  foreach(MODULE_DIR IN LISTS RNQJS_QUICKJS_MODULES)
+    get_filename_component(MODULE_NAME "${MODULE_DIR}" NAME)
+    list(APPEND RNQJS_REGISTRY_DIRS "--dir" "${MODULE_DIR}")
+    add_subdirectory("${MODULE_DIR}/android" "quickjs-modules/${MODULE_NAME}")
+    if(NOT RNQJS_QUICKJS_MODULE_TARGETS)
+      message(FATAL_ERROR
+        "${MODULE_DIR}/android did not declare RNQJS_QUICKJS_MODULE_TARGETS "
+        "(the static libraries to fold into the engine .so)")
+    endif()
+    list(APPEND RNQJS_FOLDED_TARGETS ${RNQJS_QUICKJS_MODULE_TARGETS})
+    unset(RNQJS_QUICKJS_MODULE_TARGETS)
+  endforeach()
+
+  # The registry TU names each module's install function, making a module that
+  # configured without its JSI edge a link error rather than a silently missing
+  # global. QuickJSModule.cpp declares registerGeneratedModules() weak; this
+  # strong definition in the same .so wins.
+  set(RNQJS_REGISTRY "${CMAKE_CURRENT_BINARY_DIR}/generated/QuickJSGeneratedModules.cpp")
+  find_program(RNQJS_NODE NAMES node REQUIRED)
+  add_custom_command(
+    OUTPUT "${RNQJS_REGISTRY}"
+    COMMAND "${RNQJS_NODE}"
+            "${RNQJS_ROOT}/scripts/generate-module-registry.js"
+            ${RNQJS_REGISTRY_DIRS}
+            --out "${RNQJS_REGISTRY}"
+            --quiet
+    DEPENDS
+      "${RNQJS_ROOT}/scripts/generate-module-registry.js"
+    COMMENT "Generating the QuickJS module registry"
+    VERBATIM)
+endif()
+
+# 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.
+set(RNQJS_QUICKJSINSTANCE_SOURCES
   "${RNQJS_ROOT}/src/bytecode/QuickJSBytecode.cpp"
   "${RNQJS_ROOT}/src/module/QuickJSCompat.cpp"
   "${RNQJS_ROOT}/src/module/QuickJSModule.cpp"
@@ -38,6 +88,11 @@ add_library(quickjsinstancejni SHARED
   src/main/jni/JQuickJSInstance.cpp
   src/main/jni/OnLoad.cpp
 )
+if(DEFINED RNQJS_QUICKJS_MODULES)
+  list(APPEND RNQJS_QUICKJSINSTANCE_SOURCES "${RNQJS_REGISTRY}")
+endif()
+
+add_library(quickjsinstancejni SHARED ${RNQJS_QUICKJSINSTANCE_SOURCES})
 
 target_include_directories(quickjsinstancejni PRIVATE
   "${RNQJS_ROOT}/src/bytecode"
@@ -46,17 +101,34 @@ target_include_directories(quickjsinstancejni PRIVATE
   "${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
-)
+# The module archives and the quickjs archive are grouped so the linker
+# resolves references in both directions; the modules are whole-archived because
+# nothing references their platform objects except names Java resolves at
+# runtime, and their initializers must run at load.
+if(RNQJS_FOLDED_TARGETS)
+  target_link_libraries(quickjsinstancejni
+    -Wl,--start-group
+    -Wl,--whole-archive
+    ${RNQJS_FOLDED_TARGETS}
+    -Wl,--no-whole-archive
+    quickjs
+    -Wl,--end-group
+    fbjni::fbjni
+    ReactAndroid::jsi
+    ReactAndroid::reactnative
+    android
+    log
+  )
+else()
+  target_link_libraries(quickjsinstancejni
+    quickjs
+    fbjni::fbjni
+    ReactAndroid::jsi
+    ReactAndroid::reactnative
+    android
+    log
+  )
+endif()
 
 # --- Chrome DevTools Protocol ----------------------------------------------
 #

package/android/build.gradle

@@ -2,7 +2,8 @@ buildscript {
   ext.ReactNativeQuickJS = [
     kotlinVersion: "2.0.21",
     minSdkVersion: 24,
-    compileSdkVersion: 36
+    compileSdkVersion: 36,
+    ndkVersion: "29.0.14206865"
   ]
 
   ext.getExtOrDefault = { prop ->
@@ -31,12 +32,7 @@ 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")
-  }
-
+  ndkVersion getExtOrDefault("ndkVersion")
   compileSdkVersion getExtOrDefault("compileSdkVersion")
 
   defaultConfig {
@@ -59,6 +55,9 @@ android {
         arguments "-DANDROID_STL=c++_shared",
                   "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON",
                   "-DREACT_NATIVE_DIR=${reactNativeDir()}"
+        if (quickjsModuleDirs().size() > 0) {
+          arguments "-DRNQJS_QUICKJS_MODULES=${quickjsModuleDirs().join(';')}"
+        }
 
         // Left unset, CMakeLists.txt takes the DevTools backend from the build
         // type. -PrnqjsEnableCdp=true|false forces it either way.
@@ -142,6 +141,31 @@ def reactNativeArchitectures() {
   return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
 }
 
+// Autolinked QuickJS modules (@react-native-quickjs/* declaring
+// reactNativeQuickJSModule with an android/ dir), folded into this engine's
+// single .so.
+def quickjsModuleDirs() {
+  def engineRoot = projectDir.parentFile
+  // Consumer: engineRoot is node_modules/@react-native-quickjs/quickjs.
+  // Monorepo: engineRoot is the workspace root.
+  def scopes = [engineRoot.parentFile,
+                new File(engineRoot, "node_modules/@react-native-quickjs")]
+  def dirs = []
+  scopes.each { scope ->
+    if (scope == null || !scope.exists()) return
+    scope.listFiles().each { pkg ->
+      def manifest = new File(pkg, "package.json")
+      if (!manifest.exists()) return
+      def json = new groovy.json.JsonSlurper().parse(manifest)
+      if (json.reactNativeQuickJSModule && new File(pkg, "android").exists()
+          && !dirs.contains(pkg.absolutePath)) {
+        dirs << pkg.absolutePath
+      }
+    }
+  }
+  return dirs
+}
+
 dependencies {
   implementation "com.facebook.react:react-android"
   implementation "com.facebook.fbjni:fbjni:0.7.0"

package/engine/quickjs-rel/MANIFEST.json

@@ -26,13 +26,17 @@
       "name": "0006-private-symbol-keys.patch",
       "sha256": "cf4ba5df3779f81c1721abab677381de5174ed34323bcb5cee68f2f5cf572edd"
     },
+    {
+      "name": "0007-stripped-source-tostring.patch",
+      "sha256": "5543d3f33108b3666ccc2317b65afc3ae132a8a12e223ed9f6defeaef2367b8b"
+    },
     {
       "name": "9999-bc-version-bump.patch",
       "sha256": "1a89bc63c09a7411d3f5d8cacbccbb7c525ad37ec4f7f07ee130f5ade736d428"
     }
   ],
   "files": {
-    "quickjs.c": "e59a0172640094f35db7238cb9a0b4ed38152b7388142cdc9a4aa53447cfa80f",
+    "quickjs.c": "9016fa1b5e6682c0c45fef8d1b057aa44cfad95ff1eb50e3432ad520187a86e1",
     "libregexp.c": "27cd5fb4f4f0d8c05fea4cb0ddcd4dede7f39364e87f0f5610cfc25a89908158",
     "libunicode.c": "d88f53190ad772dd09b2beb93ffb8fc3097852f4987485aac8663a00189c43eb",
     "dtoa.c": "a8d2cf2d04db406e0c16acdd95ab0e709d309902865722f41dac07a1ba5676af",

package/engine/quickjs-rel/quickjs.c

@@ -43038,17 +43038,23 @@ static JSValue js_function_toString(JSContext *ctx, JSValueConst this_val,
                                     int argc, JSValueConst *argv)
 {
     JSObject *p;
+    bool source_stripped;
     JSFunctionKindEnum func_kind = JS_FUNC_NORMAL;
 
     if (check_function(ctx, this_val))
         return JS_EXCEPTION;
 
     p = JS_VALUE_GET_OBJ(this_val);
+    source_stripped = false;
     if (js_class_has_bytecode(p->class_id)) {
         JSFunctionBytecode *b = p->u.func.function_bytecode;
         /* `b->source` must be pure ASCII or UTF-8 encoded */
         if (b->source)
             return JS_NewStringLen(ctx, b->source, b->source_len);
+        /* The embedded source was stripped at compile time (qjsc
+         * --strip-source); only the declaration survives, so say so instead
+         * of pretending this is a native C function. */
+        source_stripped = true;
     }
     {
         JSValue name;
@@ -43069,7 +43075,10 @@ static JSValue js_function_toString(JSContext *ctx, JSValueConst this_val,
             pref = "async function *";
             break;
         }
-        suff = "() {\n    [native code]\n}";
+        if (source_stripped)
+            suff = "() {\n    [stripped source]\n}";
+        else
+            suff = "() {\n    [native code]\n}";
         name = JS_GetProperty(ctx, this_val, JS_ATOM_name);
         if (JS_IsUndefined(name))
             name = js_empty_string(ctx->rt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-quickjs/quickjs",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "QuickJS JSI runtime for React Native, built from source",
   "keywords": [
     "react-native",
@@ -35,6 +35,7 @@
     "modules/hermes-compat/src",
     "scripts/postinstall.js",
     "scripts/bytecode",
+    "scripts/generate-module-registry.js",
     "scripts/react_native_quickjs_pods.rb",
     "*.podspec",
     "bin",
@@ -48,6 +49,7 @@
   ],
   "workspaces": [
     "modules/text-encoding",
+    "modules/intl",
     "example"
   ],
   "scripts": {
@@ -66,8 +68,9 @@
     "example": "npm run --workspace @react-native-quickjs/example",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "release:module": "npm publish -w @react-native-quickjs/text-encoding",
-    "release:alpha": "npm publish --tag alpha"
+    "release": "node scripts/release.js",
+    "release:alpha": "node scripts/release.js --tag alpha",
+    "release:module": "node scripts/release-module.js"
   },
   "peerDependencies": {
     "react": "*",
@@ -99,6 +102,6 @@
     }
   },
   "dependencies": {
-    "@react-native-quickjs/text-encoding": "1.0.0"
+    "@react-native-quickjs/text-encoding": "1.0.1"
   }
 }

package/scripts/generate-module-registry.js

@@ -0,0 +1,234 @@
+#!/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.
+ */
+
+/*
+ * Emits a C++ file that calls each autolinked QuickJS module's install
+ * function by name.
+ *
+ * Naming the function is what stops the linker dropping a static library's
+ * object file, which would otherwise leave the module silently uninstalled.
+ *
+ *   node scripts/generate-module-registry.js [--dir <pkg> ...] [--out <file>]
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const argv = process.argv.slice(2);
+const opt = (name, dflt = null) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : dflt;
+};
+
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`
+generate-module-registry — autolink QuickJS modules
+
+  node scripts/generate-module-registry.js [options]
+
+Options
+  --root <dir>   project root to scan from (default: cwd)
+  --out <file>   output path (default: <root>/build/QuickJSGeneratedModules.cpp)
+  --dir <dir>    an explicit module package directory (repeatable). When given,
+                 the registry is exactly these modules -- authoritative, for an
+                 app build that must only reference linked modules.
+  --only <names> keep only these discovered modules (comma-separated names)
+  --json         print the discovered modules as JSON and write nothing
+  --quiet        suppress the summary`);
+  process.exit(0);
+}
+
+const root = path.resolve(opt('root', process.cwd()));
+const outPath = path.resolve(
+  opt('out', path.join(root, 'build', 'QuickJSGeneratedModules.cpp'))
+);
+const only = opt('only', null) ? new Set(opt('only').split(',')) : null;
+const asJson = argv.includes('--json');
+const quiet = argv.includes('--quiet');
+
+/**
+ * Directories to scan. Monorepos hoist to the root `node_modules`, and this
+ * repository keeps its first-party modules in `modules/`, uninstalled.
+ */
+function candidateDirs() {
+  const dirs = [];
+  const nodeModules = path.join(root, 'node_modules');
+  if (fs.existsSync(nodeModules)) dirs.push(nodeModules);
+
+  const modules = path.join(root, 'modules');
+  if (fs.existsSync(modules)) dirs.push(modules);
+
+  return dirs;
+}
+
+/** Reads a package.json, or null when it is missing or invalid. */
+function readPackage(dir) {
+  try {
+    const raw = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function moduleFromDir(dir) {
+  const pkg = readPackage(dir);
+  const spec = pkg && pkg.reactNativeQuickJSModule;
+  if (!spec || !spec.install) return null;
+  return {
+    name: pkg.name || path.basename(dir),
+    install: spec.install,
+    header: spec.header || null,
+    priority: typeof spec.priority === 'number' ? spec.priority : 0,
+    dir,
+  };
+}
+
+function discover() {
+  const found = new Map(); // name -> { name, install, header, dir }
+
+  for (const base of candidateDirs()) {
+    let entries;
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+    // Scoped packages nest one level deeper: node_modules/@scope/name.
+    const dirs = entry.name.startsWith('@')
+        ? fs
+            .readdirSync(path.join(base, entry.name), { withFileTypes: true })
+            .filter((e) => e.isDirectory() || e.isSymbolicLink())
+            .map((e) => path.join(base, entry.name, e.name))
+        : [path.join(base, entry.name)];
+
+      for (const dir of dirs) {
+        const m = moduleFromDir(dir);
+        if (m && !found.has(m.name)) found.set(m.name, m); // first wins
+      }
+    }
+  }
+
+  // Deterministic output, so an unchanged build does not retrigger everything
+  // downstream of the registry.
+  return [...found.values()].sort(
+    (a, b) => a.priority - b.priority || a.name.localeCompare(b.name)
+  );
+}
+
+// --dir is authoritative: the registry becomes exactly these modules, which is
+// what an app build wants. node_modules holds packages that are present but not
+// linked (transitive dependencies), and referencing their symbols would fail
+// the link.
+const explicitDirs = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--dir' && argv[i + 1]) explicitDirs.push(path.resolve(argv[i + 1]));
+}
+
+let modules;
+if (explicitDirs.length > 0) {
+  const seen = new Map();
+  for (const dir of explicitDirs) {
+    const m = moduleFromDir(dir);
+    if (m && !seen.has(m.name)) seen.set(m.name, m);
+  }
+  modules = [...seen.values()].sort(
+    (a, b) => a.priority - b.priority || a.name.localeCompare(b.name)
+  );
+} else {
+  modules = discover();
+  if (only) {
+    // An allow-list over the discovered modules.
+    modules = modules.filter((m) => only.has(m.name));
+  }
+}
+
+if (asJson) {
+  console.log(JSON.stringify(modules, null, 2));
+  process.exit(0);
+}
+
+const isValidIdentifier = (s) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s);
+
+for (const m of modules) {
+  if (!isValidIdentifier(m.install)) {
+    console.error(
+      `[generate-module-registry] ${m.name}: reactNativeQuickJSModule.install ` +
+        `must be a C identifier, got ${JSON.stringify(m.install)}`
+    );
+    process.exit(1);
+  }
+}
+
+const lines = [];
+lines.push('// Generated by scripts/generate-module-registry.js — do not edit.');
+lines.push('');
+lines.push('#include <jsi/jsi.h>');
+lines.push('');
+lines.push('#include "QuickJSModule.h"');
+lines.push('');
+
+if (modules.length === 0) {
+  lines.push('// No autolinked modules were found.');
+  lines.push('');
+}
+
+lines.push('extern "C" {');
+for (const m of modules) {
+  lines.push(`// ${m.name}`);
+  lines.push(`void ${m.install}(facebook::jsi::Runtime &);`);
+}
+lines.push('}');
+lines.push('');
+lines.push('namespace qjs {');
+lines.push('');
+lines.push('void registerGeneratedModules() {');
+if (modules.length === 0) {
+  lines.push('  // Nothing to register.');
+}
+for (const m of modules) {
+  lines.push(`  registerModule("${m.name}", ${m.install}, ${m.priority});`);
+}
+lines.push('}');
+lines.push('');
+lines.push('} // namespace qjs');
+lines.push('');
+
+const output = lines.join('\n');
+
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+
+// Only write when the content differs, so an unchanged registry does not
+// retrigger a rebuild of everything downstream of it.
+let existing = null;
+try {
+  existing = fs.readFileSync(outPath, 'utf8');
+} catch {
+  /* first run */
+}
+
+if (existing !== output) {
+  fs.writeFileSync(outPath, output);
+}
+
+if (!quiet) {
+  if (modules.length === 0) {
+    console.log('[generate-module-registry] no QuickJS modules found');
+  } else {
+    console.log(
+      `[generate-module-registry] ${modules.length} module(s) -> ${path.relative(root, outPath)}`
+    );
+    for (const m of modules) {
+      console.log(`  ${m.name} -> ${m.install}()`);
+    }
+  }
+}

package/scripts/react_native_quickjs_pods.rb

@@ -17,6 +17,9 @@
 #     end
 #   end
 
+require "json"
+require "pathname"
+
 # react-native-worklets and react-native-reanimated declare
 # `s.dependency 'React-hermes'` unconditionally, and use_quickjs! never declares
 # that pod, so `pod install` cannot resolve it. Neither uses anything from it:
@@ -134,6 +137,7 @@ end
 
 def react_native_quickjs_post_install(installer)
   react_native_quickjs_add_bytecode_phase(installer)
+  react_native_quickjs_add_module_registry(installer)
 
   # Debug only, matching the gate React Native puts on its own inspector.
   # QuickJSInstance::debuggerEnabledByDefault() already refuses to attach in a
@@ -235,3 +239,129 @@ def react_native_quickjs_append(installer, pod_name, setting, value, debug_only:
     config.build_settings[setting] = "#{current} #{value}"
   end
 end
+
+# The generated module registry, compiled into the app target.
+#
+# A QuickJS module's QJS_REGISTER_MODULE static initializer is dropped by the
+# linker from a static archive unless something references its object file, so
+# the registry calls each module's install function by name. The reference must
+# live in the last-linked thing -- the app target -- because CocoaPods orders
+# module pods before the engine pod. A script phase regenerates the TU below
+# before Sources compile; the host build exercises the same path in
+# quickjs_generated_modules_tests.
+MODULE_REGISTRY_PHASE = "[ReactNativeQuickJS] Generate module registry"
+
+def react_native_quickjs_add_module_registry(installer)
+  engine_root = File.expand_path("..", __dir__)
+  generator = "scripts/generate-module-registry.js"
+
+  sandbox = Pod::Config.instance.sandbox
+  sandbox_root = sandbox.root.to_s
+
+  module_dirs = []
+  dev_pods = sandbox.send(:development_pods)
+  (installer.pod_targets || []).each do |pod_target|
+    next unless pod_target.name.start_with?("react-native-quickjs-")
+
+    # The podspec's directory is the package root; for a local (file:) pod it
+    # comes from CocoaPods' development_pods storage, not a layout guess.
+    spec_file = dev_pods[pod_target.pod_name].to_s
+    pkg_root = spec_file.empty? ? "" : File.dirname(spec_file)
+    if pkg_root.empty? || !File.exist?(File.join(pkg_root, "package.json"))
+      spec_file = pod_target.root_spec.defined_in_file
+      pkg_root = spec_file ? File.dirname(spec_file) : ""
+    end
+    next if pkg_root.empty?
+    pkg = File.join(pkg_root, "package.json")
+    next unless File.exist?(pkg)
+    next unless JSON.parse(File.read(pkg))["reactNativeQuickJSModule"]
+    module_dirs << pkg_root
+  end
+
+  # Warn rather than silently produce an empty registry when modules are linked.
+  if module_dirs.empty? && (installer.pods_project)
+    (installer.pods_project.targets).each do |t|
+      next unless t.name.start_with?("react-native-quickjs-")
+      Pod::UI.warn(
+        "[ReactNativeQuickJS] found pod #{t.name} but no package.json with " \
+        "reactNativeQuickJSModule next to it; module registry will be empty."
+      )
+    end
+  end
+
+  return if module_dirs.empty?
+
+  node_binary = ENV["NODE_BINARY"] || "node"
+
+  # The registry TU includes QuickJSModule.h (which includes jsi/jsi.h). The
+  # module pods expose those headers to themselves, not to the app, so the app
+  # target gets the engine's module headers and the Pods React-jsi headers.
+  jsi_headers = File.join(sandbox_root, "Headers", "Public", "React-jsi")
+  engine_src = File.join(engine_root, "src", "module")
+  engine_headers = [
+    "\"#{jsi_headers}\"",
+    "\"#{engine_src}\"",
+  ].select { |p| p.include?("$(PODS_ROOT)") || File.directory?(p.tr("\"", "")) }
+
+  installer.aggregate_targets.map(&:user_project).uniq(&:path).compact.each do |project|
+    project.native_targets.each do |target|
+      next unless target.product_type == "com.apple.product-type.application"
+
+      project_dir = File.dirname(project.path)
+      # The generated TU lives under the app project and is addressed with
+      # $SRCROOT, so nothing machine-specific is written into the project.
+      out = File.join(project_dir, "build", "generated", "QuickJSGeneratedModules.cpp")
+
+      target.build_configurations.each do |config|
+        paths = [config.build_settings["HEADER_SEARCH_PATHS"] || "$(inherited)"]
+        paths = [paths] unless paths.is_a?(Array)
+        paths = paths.flatten
+        paths.concat(engine_headers)
+        config.build_settings["HEADER_SEARCH_PATHS"] = paths.uniq.join(" ")
+      end
+
+      # Reuse an existing phase (a re-run refreshes it rather than accumulating
+      # another) and keep it ordered before Sources.
+      phase = target.build_phases.find do |p|
+        p.respond_to?(:display_name) && p.display_name == MODULE_REGISTRY_PHASE
+      end
+      phase ||= target.new_shell_script_build_phase(MODULE_REGISTRY_PHASE)
+
+      # The generated file is declared as an output so Compile Sources can
+      # consume it ("Build input file cannot be found" otherwise). Engine and
+      # module paths are resolved at build time through node.
+      phase.output_paths = ["$(SRCROOT)/build/generated/QuickJSGeneratedModules.cpp"]
+      rel_dirs = module_dirs.map do |d|
+        Pathname.new(d).relative_path_from(Pathname.new(engine_root)).to_s
+      end
+      phase.shell_script = <<~SH
+        set -e
+        [ -f "$SRCROOT/.xcode.env" ] && . "$SRCROOT/.xcode.env"
+        [ -f "$SRCROOT/.xcode.env.local" ] && . "$SRCROOT/.xcode.env.local"
+        : "${NODE_BINARY:=#{node_binary}}"
+        ENGINE="$("$NODE_BINARY" --print "require.resolve('@react-native-quickjs/quickjs/package.json', {paths: ['$SRCROOT']})" | xargs dirname)"
+        OUT="$SRCROOT/build/generated/QuickJSGeneratedModules.cpp"
+        mkdir -p "$(dirname "$OUT")"
+        "$NODE_BINARY" "$ENGINE/#{generator}" --dir "$ENGINE/#{rel_dirs.join('" --dir "$ENGINE/')}" \\
+          --out "$OUT" --quiet
+      SH
+
+      compile = target.build_phases.find do |p|
+        p.respond_to?(:display_name) && p.display_name == "Sources"
+      end
+      target.build_phases.delete(phase)
+      index = compile ? target.build_phases.index(compile) : nil
+      target.build_phases.insert(index, phase) if index
+
+      rel = Pathname.new(out).relative_path_from(Pathname.new(project_dir)).to_s
+      ref = project.main_group.files.find { |f| f.path == rel }
+      ref ||= project.main_group.new_file(rel)
+      target.source_build_phase.add_file_reference(ref)
+
+      Pod::UI.puts(
+        "[ReactNativeQuickJS] module registry -> #{module_dirs.map { |d| File.basename(d) }.join(', ')}".green
+      )
+    end
+    project.save
+  end
+end

package/src/module/QuickJSModule.cpp

@@ -27,6 +27,14 @@ std::vector<ModuleRegistration> &registry() {
 
 }  // namespace
 
+// Weak default: linking quickjs_jsi without the generated registry TU still
+// links, and a target that compiles that TU overrides this (clang/gcc).
+#if defined(__GNUC__) || defined(__clang__)
+__attribute__((weak)) void registerGeneratedModules() {}
+#else
+void registerGeneratedModules() {}
+#endif
+
 void registerModule(const ModuleRegistration &module) {
   if (module.install == nullptr || module.name == nullptr) {
     return;
@@ -54,6 +62,7 @@ const std::vector<ModuleRegistration> &registeredModules() {
 }
 
 void installModules(jsi::Runtime &runtime) {
+  registerGeneratedModules();
   for (const auto &module : registry()) {
     module.install(runtime);
   }

package/src/module/QuickJSModule.h

@@ -62,6 +62,16 @@ inline void registerModule(
   registerModule(ModuleRegistration{name, install, priority});
 }
 
+/**
+ * Installs autolinked modules. Defined in a translation unit generated by
+ * scripts/generate-module-registry.js, which names each module's install
+ * function so the linker cannot drop its static-library object file (the
+ * failure plain QJS_REGISTER_MODULE is subject to). Called from
+ * installModules(); registration is idempotent, so a module reached by both
+ * routes installs once.
+ */
+void registerGeneratedModules();
+
 /// `makeQuickJSRuntime()` calls this. Call it yourself only for a runtime you
 /// built by other means.
 void installModules(jsi::Runtime &runtime);