react-native 0.87.0-rc.2 → 0.87.0-rc.4

package/Libraries/Core/ReactNativeVersion.js

@@ -29,7 +29,7 @@ export default class ReactNativeVersion {
   static major: number = 0;
   static minor: number = 87;
   static patch: number = 0;
-  static prerelease: string | null = 'rc.2';
+  static prerelease: string | null = 'rc.4';
 
   static getVersionString(): string {
     return `${this.major}.${this.minor}.${this.patch}${this.prerelease != null ? `-${this.prerelease}` : ''}`;

package/React/Base/RCTVersion.m

@@ -24,7 +24,7 @@ NSDictionary* RCTGetReactNativeVersion(void)
                   RCTVersionMajor: @(0),
                   RCTVersionMinor: @(87),
                   RCTVersionPatch: @(0),
-                  RCTVersionPrerelease: @"rc.2",
+                  RCTVersionPrerelease: @"rc.4",
                   };
   });
   return __rnVersion;

package/ReactAndroid/gradle.properties

@@ -1,4 +1,4 @@
-VERSION_NAME=0.87.0-rc.2
+VERSION_NAME=0.87.0-rc.4
 react.internal.publishingGroup=com.facebook.react
 react.internal.hermesPublishingGroup=com.facebook.hermes
 

package/ReactAndroid/src/main/java/com/facebook/react/modules/systeminfo/ReactNativeVersion.kt

@@ -15,6 +15,6 @@ public object ReactNativeVersion {
     "major" to 0,
     "minor" to 87,
     "patch" to 0,
-    "prerelease" to "rc.2"
+    "prerelease" to "rc.4"
   )
 }

package/ReactCommon/cxxreact/ReactNativeVersion.h

@@ -22,7 +22,7 @@ struct ReactNativeVersionType {
   int32_t Major = 0;
   int32_t Minor = 87;
   int32_t Patch = 0;
-  std::string_view Prerelease = "rc.2";
+  std::string_view Prerelease = "rc.4";
 };
 
 constexpr ReactNativeVersionType ReactNativeVersion;

package/ReactCommon/jsinspector-modern/HostTargetTraceRecording.cpp

@@ -64,13 +64,16 @@ tracing::HostTracingProfile HostTargetTraceRecording::stop() {
   auto startTime = *startTime_;
   startTime_.reset();
 
-  return tracing::HostTracingProfile{
-      .processId = oscompat::getCurrentProcessId(),
-      .startTime = startTime,
-      .frameTimings = frameTimings_.pruneExpiredAndExtract(),
-      .instanceTracingProfiles = std::move(state.instanceTracingProfiles),
-      .runtimeSamplingProfiles = std::move(state.runtimeSamplingProfiles),
-  };
+  // Member-wise assignment instead of designated initializers:
+  // HostTracingProfile declares its special members (move-only) and is no
+  // longer an aggregate.
+  tracing::HostTracingProfile profile;
+  profile.processId = oscompat::getCurrentProcessId();
+  profile.startTime = startTime;
+  profile.frameTimings = frameTimings_.pruneExpiredAndExtract();
+  profile.instanceTracingProfiles = std::move(state.instanceTracingProfiles);
+  profile.runtimeSamplingProfiles = std::move(state.runtimeSamplingProfiles);
+  return profile;
 }
 
 void HostTargetTraceRecording::recordFrameTimings(

package/ReactCommon/jsinspector-modern/tracing/HostTracingProfile.h

@@ -23,9 +23,22 @@ namespace facebook::react::jsinspector_modern::tracing {
  * messages.
  */
 struct HostTracingProfile {
+  HostTracingProfile() = default;
+
+  // Explicitly move-only: FrameTimingSequence and RuntimeSamplingProfile are
+  // not copyable, so the implicit copy constructor is ill-formed the moment it
+  // is instantiated. Plain C++ never instantiates it, but Swift's C++ interop
+  // does when these headers are reached from an imported module, turning it
+  // into a hard compile error (Xcode 26.3).
+  HostTracingProfile(const HostTracingProfile &) = delete;
+  HostTracingProfile &operator=(const HostTracingProfile &) = delete;
+  HostTracingProfile(HostTracingProfile &&) = default;
+  HostTracingProfile &operator=(HostTracingProfile &&) = default;
+  ~HostTracingProfile() = default;
+
   // The ID of the OS-level process that this Trace Recording is associated
   // with.
-  ProcessId processId;
+  ProcessId processId{};
 
   // The timestamp at which this Trace Recording started.
   HighResTimeStamp startTime;

package/ReactCommon/jsinspector-modern/tracing/TraceRecordingState.h

@@ -31,6 +31,17 @@ struct TraceRecordingState {
   {
   }
 
+  // Explicitly move-only: RuntimeSamplingProfile is not copyable, so the
+  // implicit copy constructor is ill-formed the moment it is instantiated.
+  // Plain C++ never instantiates it, but Swift's C++ interop (ClangImporter)
+  // does when a consumer imports these headers as part of a module, turning
+  // it into a hard compile error (Xcode 26.3).
+  TraceRecordingState(const TraceRecordingState &) = delete;
+  TraceRecordingState &operator=(const TraceRecordingState &) = delete;
+  TraceRecordingState(TraceRecordingState &&) = default;
+  TraceRecordingState &operator=(TraceRecordingState &&) = default;
+  ~TraceRecordingState() = default;
+
   // The mode of this Trace Recording.
   tracing::Mode mode;
 

package/ReactCommon/react/nativemodule/dom/NativeDOM.cpp

@@ -198,10 +198,6 @@ jsi::Value NativeDOM::getParentNode(
   }
 
   auto shadowNode = getShadowNode(rt, nativeNodeReference);
-  if (isRootShadowNode(*shadowNode)) {
-    // The parent of the root node is the document.
-    return jsi::Value{shadowNode->getSurfaceId()};
-  }
 
   auto currentRevision =
       getCurrentShadowTreeRevision(rt, shadowNode->getSurfaceId());
@@ -209,6 +205,16 @@ jsi::Value NativeDOM::getParentNode(
     return jsi::Value::undefined();
   }
 
+  // The parent of the surface's root node is the document. Only the actual
+  // root node qualifies: nested nodes that carry the `RootNodeKind` trait
+  // (e.g. <Modal>, portals/overlays) still have a real parent in the shadow
+  // tree and must report it. Otherwise capture/bubble event propagation is
+  // silently severed at that boundary (a listener on an ancestor rendered
+  // above the modal would never receive descendant focus/blur, etc.).
+  if (ShadowNode::sameFamily(*currentRevision, *shadowNode)) {
+    return jsi::Value{shadowNode->getSurfaceId()};
+  }
+
   auto parentShadowNode = dom::getParentNode(currentRevision, *shadowNode);
   if (parentShadowNode == nullptr) {
     return jsi::Value::undefined();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native",
-  "version": "0.87.0-rc.2",
+  "version": "0.87.0-rc.4",
   "description": "A framework for building native apps using React",
   "license": "MIT",
   "repository": {
@@ -42,7 +42,9 @@
       "types": null,
       "default": "./Libraries/*.js"
     },
-    "./scripts/*": "./scripts/*",
+    "./scripts/*": "./scripts/*.js",
+    "./scripts/*.sh": "./scripts/*.sh",
+    "./scripts/*.rb": "./scripts/*.rb",
     "./asset-registry": {
       "types": null,
       "default": "./src/asset-registry.js"
@@ -148,12 +150,12 @@
     }
   },
   "dependencies": {
-    "@react-native/asset-utils": "0.87.0-rc.2",
-    "@react-native/codegen": "0.87.0-rc.2",
-    "@react-native/community-cli-plugin": "0.87.0-rc.2",
-    "@react-native/gradle-plugin": "0.87.0-rc.2",
-    "@react-native/normalize-colors": "0.87.0-rc.2",
-    "@react-native/virtualized-lists": "0.87.0-rc.2",
+    "@react-native/asset-utils": "0.87.0-rc.4",
+    "@react-native/codegen": "0.87.0-rc.4",
+    "@react-native/community-cli-plugin": "0.87.0-rc.4",
+    "@react-native/gradle-plugin": "0.87.0-rc.4",
+    "@react-native/normalize-colors": "0.87.0-rc.4",
+    "@react-native/virtualized-lists": "0.87.0-rc.4",
     "anser": "^1.4.9",
     "ansi-regex": "^5.0.0",
     "babel-plugin-syntax-hermes-parser": "0.36.1",

package/scripts/cocoapods/rncore.rb

@@ -568,6 +568,7 @@ class ReactNativeCoreUtils
         # Quoted so a $(PODS_ROOT) containing spaces stays a single clang argument.
         module_map_flag = " \"-fmodule-map-file=$(PODS_ROOT)/React-Core-prebuilt/Headers/module.modulemap\""
         ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_CFLAGS", module_map_flag)
+        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_CPLUSPLUSFLAGS", module_map_flag)
         ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_SWIFT_FLAGS", " -Xcc" + module_map_flag)
     end
 end

package/scripts/replace-rncore-version.js

@@ -59,7 +59,7 @@ function replaceRNCoreConfiguration(
   configuration /*: string */,
   version /*: string */,
   podsRoot /*: string */,
-) {
+) /*: void */ {
   // Filename comes from rncore.rb
   const tarballURLPath = `${podsRoot}/ReactNativeCore-artifacts/reactnative-core-${version.toLowerCase()}-${configuration.toLowerCase()}.tar.gz`;
 
@@ -73,18 +73,6 @@ function replaceRNCoreConfiguration(
   const tmpExtractDir = path.join(tmpDir, 'React-Core-prebuilt');
   fs.mkdirSync(tmpExtractDir, {recursive: true});
 
-  // Preserve Expo-generated modulemap before replacing directories
-  const useFrameworksModulemapName = 'React-use-frameworks.modulemap';
-  const useFrameworksModulemapPath = path.join(
-    finalLocation,
-    useFrameworksModulemapName,
-  );
-  let savedModulemap = null;
-  if (fs.existsSync(useFrameworksModulemapPath)) {
-    console.log('Preserving', useFrameworksModulemapName);
-    savedModulemap = fs.readFileSync(useFrameworksModulemapPath);
-  }
-
   try {
     console.log('Extracting the tarball to temp dir', tarballURLPath);
     const result = spawnSync(
@@ -110,98 +98,30 @@ function replaceRNCoreConfiguration(
       );
     }
 
-    // Delete only directories in finalLocation (e.g. the React.xcframework) -
-    // not files, so any sibling files written during pod install are preserved.
-    const dirs = fs
-      .readdirSync(finalLocation, {withFileTypes: true})
-      .filter(dirent => dirent.isDirectory());
-    for (const dirent of dirs) {
-      const direntName =
-        typeof dirent.name === 'string' ? dirent.name : dirent.name.toString();
-      const dirPath = `${finalLocation}/${direntName}`;
-      console.log('Removing directory', dirPath);
-      fs.rmSync(dirPath, {force: true, recursive: true});
-    }
-
-    // Move extracted directories from temp to final location
-    const extractedEntries = fs
-      .readdirSync(tmpExtractDir, {withFileTypes: true})
-      .filter(dirent => dirent.isDirectory());
-    for (const dirent of extractedEntries) {
-      const direntName =
-        typeof dirent.name === 'string' ? dirent.name : dirent.name.toString();
-      const src = path.join(tmpExtractDir, direntName);
-      const dst = path.join(finalLocation, direntName);
-      const mvResult = spawnSync('mv', [src, dst], {stdio: 'inherit'});
-      if (mvResult.status !== 0) {
-        // Fallback: copy recursively then remove source
-        console.log(`mv failed for ${direntName}, falling back to cp -R`);
-        const cpResult = spawnSync('cp', ['-R', src, dst], {
-          stdio: 'inherit',
-        });
-        if (cpResult.status !== 0) {
-          throw new Error(
-            `cp fallback failed with exit code ${cpResult.status}`,
-          );
-        }
+    // Replace only the compiled framework. Headers/ is flattened from
+    // ReactNativeHeaders by the podspec prepare_command, and the prebuild
+    // compose job emits one set of those headers for both configurations, so a
+    // config switch leaves them identical. Leaving them alone keeps
+    // Headers/module.modulemap — which consumers activate through
+    // -fmodule-map-file — in place for the whole build; deleting and recreating
+    // it mid-build lets a concurrent dependency scan miss it, and the React
+    // module then precompiles without it (#57803).
+    const dest = path.join(finalLocation, 'React.xcframework');
+    console.log('Replacing', dest);
+    fs.rmSync(dest, {force: true, recursive: true});
+    const mvResult = spawnSync('mv', [xcfwPath, dest], {stdio: 'inherit'});
+    if (mvResult.status !== 0) {
+      // Fallback: copy recursively then remove source
+      console.log('mv failed for React.xcframework, falling back to cp -R');
+      const cpResult = spawnSync('cp', ['-R', xcfwPath, dest], {
+        stdio: 'inherit',
+      });
+      if (cpResult.status !== 0) {
+        throw new Error(`cp fallback failed with exit code ${cpResult.status}`);
       }
     }
-
-    // The podspec prepare_command flattens ReactNativeHeaders' headers into a
-    // top-level Headers/ dir, but it does not re-run on a config swap. Mirror
-    // it here: re-flatten the headers (identical across slices) and drop the
-    // now-redundant xcframework so $(PODS_ROOT)/React-Core-prebuilt/Headers
-    // keeps resolving <react/...>, <yoga/...>, etc.
-    //
-    // Fail closed when the swapped-in tarball lacks ReactNativeHeaders: the
-    // directory purge above already deleted the previous Headers/, so
-    // continuing silently would leave the injected -fmodule-map-file flag
-    // dangling and break every <react/...> include only on a config switch —
-    // with no pointer to the version-skewed artifact that caused it.
-    const rnhXcfw = path.join(finalLocation, 'ReactNativeHeaders.xcframework');
-    if (!fs.existsSync(rnhXcfw)) {
-      throw new Error(
-        `ReactNativeHeaders.xcframework not found in the extracted tarball at ${finalLocation}. ` +
-          'The downloaded artifact predates the headers-spec layout (or is incomplete); ' +
-          'use a prebuilt tarball matching this react-native version.',
-      );
-    }
-    const slice = fs
-      .readdirSync(rnhXcfw, {withFileTypes: true})
-      .find(
-        dirent =>
-          dirent.isDirectory() &&
-          fs.existsSync(path.join(rnhXcfw, dirent.name.toString(), 'Headers')),
-      );
-    if (!slice) {
-      throw new Error(
-        `No slice with a Headers directory found inside ${rnhXcfw}.`,
-      );
-    }
-    const headersDest = path.join(finalLocation, 'Headers');
-    fs.rmSync(headersDest, {force: true, recursive: true});
-    const cpHeaders = spawnSync(
-      'cp',
-      ['-R', path.join(rnhXcfw, slice.name.toString(), 'Headers'), headersDest],
-      {stdio: 'inherit'},
-    );
-    if (cpHeaders.status !== 0) {
-      throw new Error(
-        `Flattening ReactNativeHeaders failed with exit code ${cpHeaders.status}`,
-      );
-    }
-    fs.rmSync(rnhXcfw, {force: true, recursive: true});
   } finally {
-    // Clean up temp directory
     fs.rmSync(tmpDir, {force: true, recursive: true});
-
-    // Restore Expo-generated modulemap after directory replacement.
-    // Runs in finally so it is not skipped if mv/cp partially fails.
-    if (savedModulemap != null) {
-      const restoredPath = path.join(finalLocation, useFrameworksModulemapName);
-      fs.writeFileSync(restoredPath, savedModulemap);
-      console.log('Restored', useFrameworksModulemapName);
-    }
   }
 }
 
@@ -227,29 +147,33 @@ function main(
   console.log('Done replacing React Native prebuilt');
 }
 
-// This script is executed in the Pods folder, which is usually not synched to Github, so it should be ok
-const argv = yargs
-  .option('c', {
-    alias: 'configuration',
-    description:
-      'Configuration to use to download the right React-Core prebuilt version. Allowed values are "Debug" and "Release".',
-  })
-  .option('r', {
-    alias: 'reactNativeVersion',
-    description:
-      'The Version of React Native associated with the React-Core prebuilt tarball.',
-  })
-  .option('p', {
-    alias: 'podsRoot',
-    description: 'The path to the Pods root folder',
-  })
-  .usage('Usage: $0 -c Debug -r <version> -p <path/to/react-native>').argv;
-
-// $FlowFixMe[prop-missing]
-const configuration = argv.configuration;
-// $FlowFixMe[prop-missing]
-const version = argv.reactNativeVersion;
-// $FlowFixMe[prop-missing]
-const podsRoot = argv.podsRoot;
-
-main(configuration, version, podsRoot);
+if (require.main === module) {
+  // This script is executed in the Pods folder, which is usually not synched to Github, so it should be ok
+  const argv = yargs
+    .option('c', {
+      alias: 'configuration',
+      description:
+        'Configuration to use to download the right React-Core prebuilt version. Allowed values are "Debug" and "Release".',
+    })
+    .option('r', {
+      alias: 'reactNativeVersion',
+      description:
+        'The Version of React Native associated with the React-Core prebuilt tarball.',
+    })
+    .option('p', {
+      alias: 'podsRoot',
+      description: 'The path to the Pods root folder',
+    })
+    .usage('Usage: $0 -c Debug -r <version> -p <path/to/react-native>').argv;
+
+  // $FlowFixMe[prop-missing]
+  const configuration = argv.configuration;
+  // $FlowFixMe[prop-missing]
+  const version = argv.reactNativeVersion;
+  // $FlowFixMe[prop-missing]
+  const podsRoot = argv.podsRoot;
+
+  main(configuration, version, podsRoot);
+}
+
+module.exports = {replaceRNCoreConfiguration};

package/scripts/setup-apple-spm.js

@@ -55,6 +55,7 @@
  *                               must contain debug/ and release/ cache slots.
  *   [advanced] --download <auto|skip|force> Artifact policy (default: auto).
  *   [advanced] --skip-codegen   Skip the react-native codegen step.
+ *   [advanced] --config-command <json> Override the autolinking config command.
  *
  * Steps performed (add/update):
  *   1. react-native codegen → build/generated/ios/ + install SPM codegen template
@@ -83,14 +84,19 @@ const {
 } = require('./spm/generate-spm-autolinking');
 const {
   generateAutolinkingConfig,
+  parseConfigCommandJson,
+  readEnvConfigCommand,
+  resolveEnvConfigCommand,
 } = require('./spm/generate-spm-autolinking-config');
 const {main: generatePackage} = require('./spm/generate-spm-package');
 const {findSourcePath} = require('./spm/generate-spm-package');
 const {
+  SPM_INJECTED_MARKER,
   cleanupDanglingJavaScriptCoreRef,
   cleanupLeftoverPodsGroup,
   findInjectedXcodeproj,
   injectSpmIntoExistingXcodeproj,
+  readPinnedConfigCommand,
   removeSpmInjection,
 } = require('./spm/generate-spm-xcodeproj');
 const {scaffoldAll} = require('./spm/scaffold-package-swift');
@@ -187,6 +193,11 @@ function parseArgs(argv /*: Array<string> */) /*: SetupArgs */ {
       default: false,
       describe: '[advanced] Skip the react-native codegen step',
     })
+    .option('config-command', {
+      type: 'string',
+      describe:
+        '[advanced] JSON array of the argv used to generate autolinking.json, overriding the default @react-native-community/cli config command. Also settable via RCT_SPM_AUTOLINKING_CONFIG_COMMAND. Either way `add`/`update` remembers the value in .spm-injected.json, so later runs and Xcode builds reuse it. Example: \'["npx","expo-modules-autolinking","react-native-config","--json","--platform","ios"]\'',
+    })
     .usage(
       'Usage: $0 [action] [options]\n\nSets up Swift Package Manager support in a React Native app.',
     )
@@ -214,6 +225,10 @@ function parseArgs(argv /*: Array<string> */) /*: SetupArgs */ {
     version: parsed.version ?? null,
     artifacts: parsed.artifacts ?? null,
     skipCodegen: parsed['skip-codegen'],
+    configCommand:
+      parsed['config-command'] != null
+        ? parseConfigCommandJson(parsed['config-command'], '--config-command')
+        : null,
     downloadPolicy: parsed.download,
     productName: parsed['product-name'] ?? null,
     xcodeprojPath: parsed.xcodeproj ?? null,
@@ -833,6 +848,7 @@ async function setupXcodeproj(
     // (injectSpmIntoExistingXcodeproj preserves it — see
     // generate-spm-xcodeproj.js).
     artifactsVersionOverride: args.version ?? null,
+    configCommand: resolveConfigCommandToPin(args),
   });
   if (result.status !== 'injected') {
     logError(`SPM injection failed: ${result.reason}`);
@@ -892,6 +908,88 @@ function logNextSteps(
   log('To remove SPM later: `npx react-native spm deinit`');
 }
 
+// The autolinking config command for this run: an explicit `--config-command`
+// first, then the value a previous `add`/`update` pinned into the injection
+// marker. undefined means "no explicit command", which is what makes
+// generateAutolinkingConfig fall back to RCT_SPM_AUTOLINKING_CONFIG_COMMAND and
+// then to the built-in default — so the pin has to be WITHHELD while the env
+// var is set, or a stale pin would outrank a developer's env override.
+function resolveExplicitConfigCommand(
+  args /*: SetupArgs */,
+  appRoot /*: string */,
+) /*: Array<string> | void */ {
+  if (args.configCommand != null) {
+    return args.configCommand;
+  }
+  if (readEnvConfigCommand() != null) {
+    return undefined;
+  }
+  const pinned = readPinnedConfigCommand(appRoot);
+  if (pinned == null) {
+    return undefined;
+  }
+  log(
+    `Autolinking config command (pinned in ${SPM_INJECTED_MARKER}): ` +
+      pinned.join(' '),
+  );
+  return pinned;
+}
+
+// The command to record in the injection marker. The env var is resolved here
+// too, because the Xcode build phase inherits neither the flag nor the shell
+// that set it — an env-only override that went unpinned would leave the build
+// re-deriving autolinking.json with the default command. null pins nothing and
+// preserves any earlier pin. An invalid env value throws, as the flag does,
+// though `add` has already failed closed on it by this point.
+function resolveConfigCommandToPin(
+  args /*: SetupArgs */,
+) /*: ?Array<string> */ {
+  return args.configCommand ?? resolveEnvConfigCommand();
+}
+
+// Generate autolinking.json, failing closed on a config-command error.
+//
+// generateAutolinkingConfig throws ONLY when the config command itself fails —
+// a non-zero exit, unparseable output, or a config missing
+// project.ios.sourceDir. Swallowing that (the old behavior) let the run proceed
+// and emit an empty Autolinked package, which only surfaced much later as an
+// inscrutable `unable to resolve module dependency` at build time. Instead we
+// set process.exitCode = 2 (a hard Xcode build-phase error, matching the
+// RemoteVersionError path) and return null so the caller stops.
+//
+// A genuinely native-module-free app does NOT reach the error path: its command
+// exits 0 with valid, empty-dependency JSON, so generateAutolinkingConfig
+// returns normally and the empty-package path downstream stays valid.
+function generateAutolinkingConfigOrFailClosed(
+  opts /*: {
+    projectRoot: string,
+    configCommand?: Array<string>,
+    generate?: typeof generateAutolinkingConfig,
+  } */,
+) /*: ?AutolinkingConfigResult */ {
+  const generate = opts.generate ?? generateAutolinkingConfig;
+  try {
+    return generate({
+      projectRoot: opts.projectRoot,
+      configCommand: opts.configCommand,
+    });
+  } catch (e) {
+    logError(
+      `Failed to generate autolinking.json: ${e.message}\n` +
+        'The autolinking config command failed. If this app replaces ' +
+        '@react-native-community/cli autolinking (e.g. an Expo app), set ' +
+        'RCT_SPM_AUTOLINKING_CONFIG_COMMAND (or pass --config-command) to a ' +
+        'JSON argv array whose command prints the React Native CLI config, ' +
+        'e.g. \'["npx","expo-modules-autolinking","react-native-config",' +
+        '"--json","--platform","ios"]\'. An earlier `add`/`update` may also ' +
+        `have pinned a command in ${SPM_INJECTED_MARKER}; re-run with ` +
+        '--config-command to replace a stale one.',
+    );
+    process.exitCode = 2;
+    return null;
+  }
+}
+
 async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
   let appRoot = process.cwd();
   const projectRoot = findProjectRoot(appRoot);
@@ -981,16 +1079,16 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
   let autolinkingConfigResult /*: ?AutolinkingConfigResult */ = null;
   if (needsCliConfig) {
     log('Generating autolinking.json (CLI config)...');
-    try {
-      autolinkingConfigResult = generateAutolinkingConfig({projectRoot});
-      log(
-        `Wrote ${path.relative(appRoot, autolinkingConfigResult.outputPath)}`,
-      );
-    } catch (e) {
-      logError(
-        `generate-spm-autolinking-config failed: ${e.message}. External native modules may not be discovered.`,
-      );
+    autolinkingConfigResult = generateAutolinkingConfigOrFailClosed({
+      projectRoot,
+      configCommand: resolveExplicitConfigCommand(args, appRoot),
+    });
+    if (autolinkingConfigResult == null) {
+      // Fail closed: the config command errored and the helper already set
+      // process.exitCode = 2. Stop rather than emit an empty Autolinked package.
+      return;
     }
+    log(`Wrote ${path.relative(appRoot, autolinkingConfigResult.outputPath)}`);
   }
   const reactNativeRoot = resolveReactNativeRoot(
     autolinkingConfigResult,
@@ -1159,7 +1257,11 @@ module.exports = {
   main,
   detectStandardRnLayoutRedirect,
   findInjectedXcodeproj,
+  generateAutolinkingConfigOrFailClosed,
+  parseArgs,
   resolveAction,
+  resolveConfigCommandToPin,
+  resolveExplicitConfigCommand,
   shouldAutoDeintegrate,
   ensureBothArtifactFlavors,
 };

package/scripts/spm/__doc__/spm-scripts.md

@@ -137,6 +137,40 @@ accepts kebab-case equivalents (e.g. `--skip-codegen`).
 | `--artifacts <path>` | [advanced] Local artifact root containing complete `debug/` and `release/` cache slots |
 | `--download <auto\|skip\|force>` | [advanced] Artifact download policy (default: auto) |
 | `--skipCodegen` | [advanced] Skip the codegen step |
+| `--configCommand <json>` | [advanced] JSON array of the argv used to generate `autolinking.json`, overriding the default `@react-native-community/cli config` command. Also settable via the `RCT_SPM_AUTOLINKING_CONFIG_COMMAND` env var. Either way the value is remembered, so you pass it once. Example: `'["npx","expo-modules-autolinking","react-native-config","--json","--platform","ios"]'` |
+
+### The autolinking config command is remembered
+
+An app that replaces `@react-native-community/cli` autolinking (an Expo app,
+for example) has to tell `spm` how to produce `autolinking.json`. Pass the
+command once, on `add` or `update`:
+
+```bash
+npx react-native spm add --configCommand '["npx","expo-modules-autolinking","react-native-config","--json","--platform","ios"]'
+```
+
+Every action that needs `autolinking.json` — `add`, `update`, `scaffold`, and
+the build-time `sync` — resolves the command in this order:
+
+1. `--configCommand`
+2. `RCT_SPM_AUTOLINKING_CONFIG_COMMAND`
+3. the `configCommand` pinned in `MyApp.xcodeproj/.spm-injected.json` by an
+   earlier `add`/`update`
+4. the default `@react-native-community/cli config`
+
+`add`/`update` pin whichever of the first two routes supplied the command,
+validated as an argv array; a later run that passes neither keeps the existing
+pin, and passing `--configCommand` again replaces it. The pin exists because
+the **Sync SPM Autolinking** build phase inherits neither your flag nor the
+shell that exported the env var — without it, a successful `add` is followed by
+failing builds, because the phase re-derives `autolinking.json` with the
+default command. A pin never shadows the env var, so an override in your shell
+still takes effect, and a pin that no longer parses is ignored in favor of the
+default.
+
+`deinit` deletes `.spm-injected.json`, and the pin with it. A later `add`
+therefore falls back to the default command unless you pass `--configCommand`
+(or export the env var) again.
 
 ### Debug/Release flavor is automatic
 
@@ -161,7 +195,7 @@ package graph, or require a second build.
 | Path | Commit? | Why |
 |------|---------|-----|
 | `MyApp.xcodeproj/` | Yes | Your project, with SwiftPM injected in place. Holds your signing, capabilities, Build Phases — `add` only adds SwiftPM refs/settings, additively. |
-| `MyApp.xcodeproj/.spm-injected.json` | Yes | Marker recording every edit `add` made, so `deinit` can surgically reverse it and re-runs stay idempotent. |
+| `MyApp.xcodeproj/.spm-injected.json` | Yes | Marker recording every edit `add` made, so `deinit` can surgically reverse it and re-runs stay idempotent. Also pins settings later runs and Xcode builds must reuse, such as the [autolinking config command](#the-autolinking-config-command-is-remembered). |
 | `build/generated/` | No | Codegen/autolinking output; regenerated |
 | `build/xcframeworks/` | No | Symlinks to the machine-local artifact cache |
 | `Package.resolved` | No | SwiftPM resolution file; machine-specific |
@@ -335,6 +369,7 @@ across apps; refresh it with `react-native spm update --download force`.
 | "not contained in target" | Re-run setup (regenerates file-level symlinks) |
 | Codegen fails | Use `--skipCodegen` to iterate on other parts |
 | "SPM sync failed" warning | Check Xcode build log for details; node may not be in PATH — ensure `with-environment.sh` is present |
+| "Sync SPM Autolinking" build phase fails: `'npx --no-install @react-native-community/cli config' exited with status 1` | This app replaces `@react-native-community/cli` autolinking (e.g. an Expo app). Re-run `spm add`/`update` with `--configCommand` (or with `RCT_SPM_AUTOLINKING_CONFIG_COMMAND` exported) so the working command is pinned for the build phase to reuse — see [The autolinking config command is remembered](#the-autolinking-config-command-is-remembered). |
 | Autolinking not updating on build | Touch `package.json` to force a sync, or delete `build/generated/autolinking/.spm-sync-stamp` |
 | Stale SwiftPM state or corrupted build | `rm -rf build/ .build/`, then `react-native spm update`, then reopen Xcode |
 | Want to revert to CocoaPods | `react-native spm deinit`, then `pod install` |