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

package/scripts/bytecode/compile.js

@@ -0,0 +1,99 @@
+#!/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.
+ *
+ * Compiles a Metro bundle to QuickJS bytecode, in place. Run from the Xcode
+ * bundle phase and the Gradle bundle task; see README.md.
+ *
+ *   node scripts/bytecode/compile.js <bundle>
+ *
+ * Bytecode is only loadable by the engine build that produced it, so the
+ * compiler is pinned to the engine by BC_VERSION. A mismatch stops the build:
+ * shipping a bundle this engine cannot read fails at launch, on a user's
+ * device, with nothing to point at.
+ *
+ * Missing compiler for the host is not an error. The bundle is left as
+ * JavaScript, which runs -- just without the startup that bytecode buys.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..', '..');
+const COMPILERS = path.join(ROOT, 'bin', 'qjsc');
+
+/** The BC_VERSION the shipped engine sources define. */
+function engineBytecodeVersion() {
+  const engine = fs.readFileSync(path.join(ROOT, 'engine', 'quickjs-rel', 'quickjs.c'), 'utf8');
+  const found = /^#define BC_VERSION (\d+)/m.exec(engine);
+  if (!found) throw new Error('no BC_VERSION in engine/quickjs-rel/quickjs.c');
+  return Number(found[1]);
+}
+
+/** e.g. darwin-arm64. Matches the directory names the CI workflow writes. */
+function hostPlatform() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function compilerPath() {
+  const name = process.platform === 'win32' ? 'qjsc.exe' : 'qjsc';
+  return path.join(COMPILERS, hostPlatform(), name);
+}
+
+function skip(reason) {
+  console.log(`[quickjs] ${reason}; leaving the bundle as JavaScript.`);
+  process.exit(0);
+}
+
+function main(bundle) {
+  if (!bundle) {
+    console.error('usage: compile.js <bundle>');
+    process.exit(2);
+  }
+  if (!fs.existsSync(bundle)) skip(`${bundle} does not exist`);
+
+  const compiler = compilerPath();
+  if (!fs.existsSync(compiler)) skip(`no bytecode compiler for ${hostPlatform()}`);
+
+  // Zipped artifacts lose the executable bit, so a compiler can arrive in the
+  // repository unrunnable. Restoring it here is cheaper than the EACCES this
+  // would otherwise become.
+  try {
+    fs.accessSync(compiler, fs.constants.X_OK);
+  } catch {
+    fs.chmodSync(compiler, 0o755);
+  }
+
+  const manifestPath = path.join(COMPILERS, 'manifest.json');
+  const manifest = fs.existsSync(manifestPath)
+    ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    : {};
+  const engineVersion = engineBytecodeVersion();
+
+  if (manifest.bcVersion !== engineVersion) {
+    console.error(
+      `\n[quickjs] the bytecode compiler is stale.\n` +
+        `  compiler built for BC_VERSION ${manifest.bcVersion}\n` +
+        `  engine expects BC_VERSION    ${engineVersion}\n\n` +
+        `Bytecode from this compiler would not load. Rebuild the compilers\n` +
+        `(the "bytecode compilers" workflow) or unset RNQJS_BYTECODE.\n`
+    );
+    process.exit(1);
+  }
+
+  const compiled = `${bundle}.qbc`;
+  const args = process.env.RNQJS_BYTECODE_KEEP_SOURCE ? [] : ['--strip-source'];
+  execFileSync(compiler, [...args, bundle, compiled], { stdio: 'inherit' });
+  fs.renameSync(compiled, bundle);
+
+  const size = fs.statSync(bundle).size;
+  console.log(`[quickjs] compiled ${path.basename(bundle)} to bytecode (${size} bytes)`);
+}
+
+main(process.argv[2]);

package/scripts/expo/plugin.js

@@ -0,0 +1,231 @@
+/*
+ * 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.
+ *
+ * The Expo config plugin. It runs the same edits as the CLI, but through
+ * Expo's mods, so a prebuild regenerates them rather than losing them.
+ *
+ *   { "expo": { "plugins": ["@react-native-quickjs/quickjs"] } }
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  withAppDelegate,
+  withDangerousMod,
+  withGradleProperties,
+  withMainApplication,
+  withAppBuildGradle,
+} = require('@expo/config-plugins');
+
+const { edits } = require('../setup/edits');
+
+const editFor = (label) => edits.find((edit) => edit.label === label);
+
+function warnCouldNotEdit(label) {
+  console.warn(
+    `[@react-native-quickjs/quickjs] could not edit ${label}. ` +
+      'Run `npx react-native-quickjs doctor` after prebuild.'
+  );
+}
+
+/** Run one edit from edits.js over the contents of a string mod. */
+function addQuickJS(label, source) {
+  const edit = editFor(label);
+  if (edit.isApplied(source)) return source;
+
+  const edited = edit.addQuickJS(source);
+  if (edited == null) {
+    warnCouldNotEdit(label);
+    return source;
+  }
+  return edited;
+}
+
+// withGradleProperties hands over parsed items rather than text, so this one
+// does not go through edits.js.
+function withHermesOff(config) {
+  return withGradleProperties(config, (cfg) => {
+    const items = cfg.modResults.filter(
+      (i) => !(i.type === 'property' && i.key === 'hermesEnabled')
+    );
+    items.push({ type: 'property', key: 'hermesEnabled', value: 'false' });
+    cfg.modResults = items;
+    return cfg;
+  });
+}
+
+const withNoEngineDependency = (config) =>
+  withAppBuildGradle(config, (cfg) => {
+    cfg.modResults.contents = addQuickJS('android/app/build.gradle', cfg.modResults.contents);
+    return cfg;
+  });
+
+const withAndroidFactory = (config) =>
+  withMainApplication(config, (cfg) => {
+    cfg.modResults.contents = addQuickJS('MainApplication.kt', cfg.modResults.contents);
+    return cfg;
+  });
+
+const withIosFactory = (config) =>
+  withAppDelegate(config, (cfg) => {
+    cfg.modResults.contents = addQuickJS('AppDelegate.swift', cfg.modResults.contents);
+    return cfg;
+  });
+
+// There is no withPodfile, so the Podfile is edited on disk after prebuild has
+// written it.
+const withPodfile = (config) =>
+  withDangerousMod(config, [
+    'ios',
+    (cfg) => {
+      const file = path.join(cfg.modRequest.platformProjectRoot, 'Podfile');
+      if (!fs.existsSync(file)) {
+        warnCouldNotEdit('ios/Podfile');
+        return cfg;
+      }
+      fs.writeFileSync(file, addQuickJS('ios/Podfile', fs.readFileSync(file, 'utf8')));
+      return cfg;
+    },
+  ]);
+
+// Expo's ReactHost delegate hardcodes the engine:
+//
+//   override val jsRuntimeFactory: JSRuntimeFactory
+//     get() = HermesInstance()
+//
+// ExpoReactHostFactory.getDefaultReactHost does take a jsRuntimeFactory
+// parameter, and MainApplication.kt passes ours to it, but the function never
+// hands it to the delegate it builds. On Expo the argument is accepted and
+// ignored, and the app dies at launch looking for libhermestooling.so.
+//
+// So the parameter is carried the rest of the way here, which is what Expo
+// itself would do. Only React Native types appear in the patch: the `expo`
+// Gradle module does not depend on ours, so naming QuickJSInstance in that file
+// does not compile. The concrete factory is still built by MainApplication.kt,
+// in the app module, which does depend on ours.
+//
+// This edits node_modules, so a reinstall undoes it. Prebuild again after one.
+const EXPO_REACT_HOST_FACTORY =
+  'expo/android/src/main/java/expo/modules/ExpoReactHostFactory.kt';
+
+const EXPO_ENGINE_PATCH = [
+  [
+    '    private val hostHandlers: List<ReactNativeHostHandler>\n  ) : ReactHostDelegate {',
+    '    private val hostHandlers: List<ReactNativeHostHandler>,\n' +
+      '    private val jsRuntimeFactoryOverride: JSRuntimeFactory? = null\n' +
+      '  ) : ReactHostDelegate {',
+  ],
+  [
+    '        hostHandlers = hostHandlers\n      )',
+    '        hostHandlers = hostHandlers,\n' +
+      '        jsRuntimeFactoryOverride = jsRuntimeFactory\n      )',
+  ],
+  [
+    '    override val jsRuntimeFactory: JSRuntimeFactory\n      get() = HermesInstance()',
+    '    override val jsRuntimeFactory: JSRuntimeFactory\n' +
+      '      get() = jsRuntimeFactoryOverride ?: HermesInstance()',
+  ],
+];
+
+const withExpoAndroidEngine = (config) =>
+  withDangerousMod(config, [
+    'android',
+    (cfg) => {
+      const file = path.join(cfg.modRequest.projectRoot, 'node_modules', EXPO_REACT_HOST_FACTORY);
+      if (!fs.existsSync(file)) return cfg;
+
+      const source = fs.readFileSync(file, 'utf8');
+      if (source.includes('jsRuntimeFactoryOverride')) return cfg;
+
+      // All three or none: a half-applied patch does not compile.
+      if (!EXPO_ENGINE_PATCH.every(([find]) => source.includes(find))) {
+        console.warn(
+          '[@react-native-quickjs/quickjs] this version of Expo builds its ReactHost ' +
+            'differently than the plugin expects, so the app would launch on Hermes. ' +
+            'Please report this against @react-native-quickjs/quickjs.'
+        );
+        return cfg;
+      }
+
+      fs.writeFileSync(
+        file,
+        EXPO_ENGINE_PATCH.reduce((text, [find, replace]) => text.replace(find, replace), source)
+      );
+      return cfg;
+    },
+  ]);
+
+// ExpoModulesCore.podspec picks its engine by reading ENV['USE_HERMES'] itself
+// rather than calling React Native's use_hermes(), and it knows only two
+// answers: Hermes, or React-jsc. use_quickjs! sets USE_HERMES=0 truthfully, so
+// without this patch Expo resolves that to JavaScriptCore -- an engine the app
+// never instantiates, whose JSI runtime it would still compile and link.
+//
+// Taught here as a third branch on USE_THIRD_PARTY_JSC, which is React Native's
+// own name for "this app brought its own engine", so Expo depends on neither.
+// jsinspector is still needed and comes from where the Hermes branch takes it.
+//
+// Safe because nothing in expo-modules-core's iOS sources mentions Hermes --
+// the package's only makeHermesRuntime call is in its Android JNI -- so the
+// -DUSE_HERMES that this branch also drops gates nothing in this pod.
+//
+// This is the change proposed upstream; when it lands, this mod goes away.
+// It edits node_modules, so a reinstall undoes it. Prebuild again after one.
+const EXPO_PODSPEC = 'expo-modules-core/ExpoModulesCore.podspec';
+
+const EXPO_ENGINE_BRANCH = `  if use_hermes
+    s.dependency 'hermes-engine'
+    add_dependency(s, "React-jsinspector", :framework_name => 'jsinspector_modern')
+  else
+    s.dependency 'React-jsc'
+  end`;
+
+const EXPO_ENGINE_BRANCH_PATCHED = `  if ENV['USE_THIRD_PARTY_JSC'] == '1'
+    add_dependency(s, "React-jsinspector", :framework_name => 'jsinspector_modern')
+  elsif use_hermes
+    s.dependency 'hermes-engine'
+    add_dependency(s, "React-jsinspector", :framework_name => 'jsinspector_modern')
+  else
+    s.dependency 'React-jsc'
+  end`;
+
+const withExpoIosEngine = (config) =>
+  withDangerousMod(config, [
+    'ios',
+    (cfg) => {
+      const file = path.join(cfg.modRequest.projectRoot, 'node_modules', EXPO_PODSPEC);
+      if (!fs.existsSync(file)) return cfg;
+
+      const source = fs.readFileSync(file, 'utf8');
+      if (source.includes(EXPO_ENGINE_BRANCH_PATCHED)) return cfg;
+
+      if (!source.includes(EXPO_ENGINE_BRANCH)) {
+        console.warn(
+          '[@react-native-quickjs/quickjs] this version of Expo picks its engine ' +
+            'dependency differently than the plugin expects, so the app will also ' +
+            'ship an engine it never runs. It will still run on QuickJS.'
+        );
+        return cfg;
+      }
+
+      fs.writeFileSync(file, source.replace(EXPO_ENGINE_BRANCH, EXPO_ENGINE_BRANCH_PATCHED));
+      return cfg;
+    },
+  ]);
+
+module.exports = function withQuickJS(config) {
+  return [
+    withHermesOff,
+    withNoEngineDependency,
+    withAndroidFactory,
+    withIosFactory,
+    withPodfile,
+    withExpoAndroidEngine,
+    withExpoIosEngine,
+  ].reduce((c, mod) => mod(c), config);
+};

package/scripts/postinstall.js

@@ -0,0 +1,74 @@
+#!/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.
+ *
+ * postinstall, and why it is a script rather than a shell one-liner.
+ *
+ * This package is installed in two situations that need opposite behaviour:
+ *
+ *   1. THIS REPOSITORY, from git. engine/quickjs-ng is a submodule that has to
+ *      be initialised and patched, or nothing builds.
+ *
+ *   2. A CONSUMER'S node_modules, from the npm tarball. That ships
+ *      engine/quickjs-rel already patched, there is no submodule, and there is
+ *      no git repository.
+ *
+ * Running the first in the second breaks three ways at once: `git submodule
+ * update` with no .git of its own walks UP out of node_modules and operates on
+ * the consuming app's repository; engine/patches is not published, so the patch
+ * script has nothing to apply; and shelling out to a package manager assumes
+ * one the consumer may not use.
+ *
+ * So detect the situation, and in (2) do nothing at all.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.join(__dirname, '..');
+
+// engine/patches is absent from the tarball on purpose, and its absence is the
+// signal. Checking for .git would be wrong: a consumer who vendors this package
+// inside their own repository has a .git above them.
+if (!fs.existsSync(path.join(root, 'engine', 'patches'))) {
+  process.exit(0);
+}
+
+function run(label, command, args) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+
+  if (result.error || result.status !== 0) {
+    console.error(
+      `\n[react-native-quickjs] ${label} failed.\n` +
+        `  ${command} ${args.join(' ')}\n\n` +
+        'The engine sources are not usable until this succeeds. Run it by hand\n' +
+        'to see the full error.\n'
+    );
+    process.exit(1);
+  }
+}
+
+// --recursive matters: quickjs-ng has submodules of its own for its test
+// suites, and a partial checkout fails later in cmake rather than here.
+run('submodule checkout', 'git', [
+  'submodule',
+  'update',
+  '--init',
+  '--recursive',
+]);
+
+// Invoked through node rather than a package manager, so this behaves the same
+// under npm, yarn, pnpm and bun.
+run('patch application', process.execPath, [
+  path.join(root, 'scripts', 'apply-patches.js'),
+]);

package/scripts/react_native_quickjs_pods.rb

@@ -0,0 +1,237 @@
+# 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.
+#
+# Podfile helper for apps running on QuickJS.
+#
+#   require_relative '../node_modules/@react-native-quickjs/quickjs/scripts/react_native_quickjs_pods.rb'
+#
+#   target 'App' do
+#     use_quickjs!                                    # before 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)  # after
+#     end
+#   end
+
+# 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:
+# their only Hermes include is <hermes/hermes.h>, which the compatibility shim
+# provides.
+#
+# Dropped as each podspec is read, rather than by editing node_modules, so a
+# reinstall does not undo it. React Native's own podspecs are not affected: they
+# declare the same dependency behind `if use_hermes()`, which is already false.
+#
+# Only done when the shim is installed, so that without it a library asking for
+# the real Hermes still fails loudly rather than silently losing it.
+def react_native_quickjs_drop_react_hermes
+  return if ENV["RNQJS_HERMES_COMPAT"] == "0"
+
+  dependency = Pod::Specification.instance_method(:dependency)
+  Pod::Specification.send(:define_method, :dependency) do |*args, &block|
+    next if args.first.to_s == "React-hermes"
+
+    dependency.bind(self).call(*args, &block)
+  end
+end
+
+# Removes Hermes. Must run before use_react_native!, which reads all of this as
+# the podspecs are evaluated.
+def use_quickjs!
+  # Turns off every `if use_hermes()` dependency on hermes-engine at once.
+  # React Native's own use_hermes() is `!use_third_party_jsc()`, so this one
+  # flag answers for every React Native pod.
+  ENV['USE_THIRD_PARTY_JSC'] = '1'
+
+  # Set as well, because a podspec is free to read it directly rather than call
+  # use_hermes() -- Expo's does -- and to such a reader an unset USE_HERMES
+  # means "yes, Hermes". Leaving it unset would have this app claim an engine it
+  # does not have, and any library added later would be told the same.
+  #
+  # Safe alongside the flag above: error_if_try_to_use_jsc_from_core aborts on
+  # USE_HERMES=0 only while USE_THIRD_PARTY_JSC is unset or 0, which is the
+  # "asking for the JavaScriptCore that used to be in core" case, not this one.
+  #
+  # A reader that has only two engines in mind resolves this to JavaScriptCore
+  # rather than to no engine. That is what the Expo config plugin's podspec
+  # patch is for: it teaches USE_THIRD_PARTY_JSC as a third answer.
+  ENV['USE_HERMES'] = '0'
+
+  react_native_quickjs_drop_react_hermes
+
+  # On the prebuilt path hermesvm.framework carries the JSI implementation, and
+  # React-jsi.podspec drops its own jsi.cpp whenever Hermes is on. Removing
+  # Hermes there leaves every runtime, ours included, unable to link. Consumers
+  # pay for this in first-build and cold CI time.
+  ENV['RCT_USE_PREBUILT_RNCORE'] = '0'
+
+  # These declare Hermes pods in the Podfile directly, so they never consult
+  # use_hermes(). use_react_native! reaches them through `hermes_enabled`, which
+  # react_native_pods.rb:81 assigns true unconditionally -- replacing the
+  # functions is the only way to stop them.
+  Object.send(:define_method, :setup_hermes!) { |**_| }
+  Object.send(:define_method, :depend_on_js_engine) { |_spec| }
+
+  bridgeless = Object.instance_method(:setup_bridgeless!)
+  Object.send(:define_method, :setup_bridgeless!) do |**kwargs|
+    bridgeless.bind(self).call(**kwargs.merge(:use_hermes => false))
+  end
+
+  Pod::UI.puts(
+    "[ReactNativeQuickJS] Hermes removed — JavaScript runs on QuickJS.".green
+  )
+end
+
+# Compiles the release bundle to QuickJS bytecode, in a build phase placed
+# right after React Native's own bundling phase. Debug builds load JavaScript
+# from Metro and never produce a bundle, so the script exits early there.
+BYTECODE_PHASE = '[ReactNativeQuickJS] Compile JavaScript to bytecode'
+
+BYTECODE_SCRIPT = <<~SH
+  set -e
+  [ "$CONFIGURATION" = "Debug" ] && exit 0
+  [ "$RNQJS_BYTECODE" = "0" ] && exit 0
+
+  # The same files React Native's own bundle phase reads NODE_BINARY from.
+  [ -f "$SRCROOT/.xcode.env" ] && . "$SRCROOT/.xcode.env"
+  [ -f "$SRCROOT/.xcode.env.local" ] && . "$SRCROOT/.xcode.env.local"
+  : "${NODE_BINARY:=node}"
+
+  # Resolved through node, so a hoisted node_modules is found.
+  COMPILER=$("$NODE_BINARY" --print \
+    "require.resolve('@react-native-quickjs/quickjs/scripts/bytecode/compile.js', {paths: ['$SRCROOT']})")
+
+  "$NODE_BINARY" "$COMPILER" \
+    "$CONFIGURATION_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/main.jsbundle"
+SH
+
+def react_native_quickjs_add_bytecode_phase(installer)
+  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'
+      next if target.build_phases.any? { |phase| phase.display_name == BYTECODE_PHASE }
+
+      phase = target.new_shell_script_build_phase(BYTECODE_PHASE)
+      phase.shell_script = BYTECODE_SCRIPT
+
+      # Ordering matters: the bundle has to exist before it can be compiled.
+      after = target.build_phases.index do |other|
+        other.display_name.to_s.include?('Bundle React Native code and images')
+      end
+      next if after.nil?
+
+      target.build_phases.delete(phase)
+      target.build_phases.insert(after + 1, phase)
+    end
+    project.save
+  end
+end
+
+def react_native_quickjs_post_install(installer)
+  react_native_quickjs_add_bytecode_phase(installer)
+
+  # Debug only, matching the gate React Native puts on its own inspector.
+  # QuickJSInstance::debuggerEnabledByDefault() already refuses to attach in a
+  # release build, so this keeps the compiled surface in agreement.
+  react_native_quickjs_append(
+    installer, "ReactNativeQuickJS", "GCC_PREPROCESSOR_DEFINITIONS",
+    "RNQJS_ENABLE_CDP=1", :debug_only => true
+  )
+
+  # RCTCxxBridge.mm imports Hermes under `#if !defined(USE_HERMES)`, and
+  # js_engine_flags() never defines it in the non-Hermes case.
+  react_native_quickjs_append(
+    installer, "React-Core", "GCC_PREPROCESSOR_DEFINITIONS", "USE_HERMES=0"
+  )
+
+  # RCTAppSetupUtils.h imports Hermes under `#if USE_THIRD_PARTY_JSC != 1`, and
+  # React-RCTAppDelegate.podspec:21 loses the flag to a missing space -- clang
+  # receives the two joined, as -DRCT_NEW_ARCH_ENABLED=1-DUSE_THIRD_PARTY_JSC=1.
+  #
+  # Every pod target, not just React-RCTAppDelegate: any pod including that
+  # header resolves the same #if, and Expo's does, through RCTAppDelegateUmbrella
+  # -- so a targeted define builds a plain app and fails an Expo one.
+  react_native_quickjs_append_all(
+    installer, "GCC_PREPROCESSOR_DEFINITIONS", "USE_THIRD_PARTY_JSC=1"
+  )
+
+  # With the Hermes compatibility shim installed, every pod must be able to
+  # resolve <hermes/hermes.h> -- react-native-worklets decides which engine it
+  # is built for with __has_include on exactly that path. The headers cannot be
+  # published as public headers of this pod; see the HermesCompat subspec.
+  if ENV["RNQJS_HERMES_COMPAT"] != "0"
+    shim = File.expand_path("../modules/hermes-compat/include", __dir__)
+    react_native_quickjs_append_all(installer, "HEADER_SEARCH_PATHS", "\"#{shim}\"")
+    react_native_quickjs_append_all(
+      installer, "GCC_PREPROCESSOR_DEFINITIONS", "HERMES_ENABLE_DEBUGGER=1"
+    )
+  end
+
+  # createJSRuntimeFactory has an empty body under USE_THIRD_PARTY_JSC=1, which
+  # -Werror,-Wreturn-type rejects. Reachable only in an app that does not
+  # override it, and overriding it is how an app selects QuickJS at all.
+  react_native_quickjs_append(
+    installer, "React-RCTAppDelegate", "OTHER_CFLAGS", "-Wno-error=return-type"
+  )
+
+  # react-native-xcode.sh compares against the literal text `false`, so `0`,
+  # `NO` and `FALSE` all read as "use Hermes" and a release build ships a
+  # bytecode bundle QuickJS cannot execute.
+  installer.aggregate_targets
+    .map { |t| t.user_project }
+    .uniq { |p| p.path }
+    .push(installer.pods_project)
+    .compact
+    .each do |project|
+      project.build_configurations.each do |config|
+        config.build_settings["USE_HERMES"] = "false"
+      end
+      project.save()
+    end
+
+  Pod::UI.puts(
+    "[ReactNativeQuickJS] USE_HERMES=false — release bundles are compiled to " \
+    "QuickJS bytecode, not Hermes bytecode.".green
+  )
+end
+
+# Raises when the pod is absent. Every caller repairs something that otherwise
+# breaks the build, and they match React Native's pods by name -- exactly what a
+# version bump renames -- so a silent no-op would resurface much later as the
+# error it was meant to prevent.
+# Applies a setting to every pod target. Used for a flag that selects which
+# JavaScript engine header a React Native header imports: any pod that includes
+# it needs the same answer, and which pods those are is not knowable here.
+def react_native_quickjs_append_all(installer, setting, value)
+  installer.target_installation_results.pod_target_installation_results.each_value do |result|
+    result.native_target.build_configurations.each do |config|
+      current = config.build_settings[setting] || "$(inherited)"
+      current = current.join(" ") if current.is_a?(Array)
+      config.build_settings[setting] = "#{current} #{value}"
+    end
+  end
+end
+
+def react_native_quickjs_append(installer, pod_name, setting, value, debug_only: false)
+  result = installer.target_installation_results
+    .pod_target_installation_results[pod_name]
+
+  if result.nil?
+    raise "[ReactNativeQuickJS] no pod named #{pod_name}, so #{value} was not " \
+          "applied. React Native has probably renamed it; this needs updating " \
+          "in scripts/react_native_quickjs_pods.rb."
+  end
+
+  result.native_target.build_configurations.each do |config|
+    next if debug_only && config.type != :debug
+
+    current = config.build_settings[setting] || "$(inherited)"
+    current = current.join(" ") if current.is_a?(Array)
+    config.build_settings[setting] = "#{current} #{value}"
+  end
+end