fix(spm): SwiftPM Release support — NDEBUG propagation, hermesc, local-artifacts

Makes SwiftPM Release builds link + bundle (Debug already worked). Root-caused
via ios-build-matrix.sh; unblocks RN-Tester + community-Fabric SPM Release.

- (A) NDEBUG propagation. The Release React.framework strips
  DebugStringConvertible's vtable (and shifts the ShadowNode layout that
  inherits it) under NDEBUG, but the autolinked Fabric synth targets compiled
  with zero RN defines → undefined-symbol / layout-mismatch at link. Emit
  `.define("DEBUG", .when(.debug))` + `.define("NDEBUG", .when(.release))` on
  every autolinked C++ target: scaffolded community libs
  (scaffold-package-swift.js, SCAFFOLDER_VERSION 18→19 so existing scaffolds
  regenerate), synth wrappers, and inline spm.module targets
  (generate-spm-autolinking.js). NDEBUG-only is deliberate: Debug is green with
  no defines, so the always-on RN defines are provably unneeded — NDEBUG is the
  sole Debug↔Release divergence. Mirrors packages/react-native/Package.swift.
- (B) hermesc resolution. Under SPM there is no hermes-engine pod, so
  react-native-xcode.sh's `$PODS_ROOT/hermes-engine/.../hermesc` fallback
  resolves to a non-existent path and Release Hermes bundling fails for every
  SPM app. Inject HERMES_CLI_PATH (=$(REACT_NATIVE_PATH)/../hermes-compiler/
  hermesc/osx-bin/hermesc) via mergeReactBuildSettings; react-native-xcode.sh
  honors a pre-set value before its pod fallback, and an existing user value is
  left untouched. Reversed byte-for-byte on deinit (covered by the round-trip test).
- (Major #3) `--artifacts <local.xcframework>`: artifacts.json now also records
  ReactNativeHeaders + ReactNativeDependenciesHeaders (they ship beside their
  binaries in the tarballs). They are required by validateArtifactsCache /
  generate-spm-package; omitting them made the local slot report incomplete and
  forced a full Maven download, defeating "use it directly".

Tests: NDEBUG defines asserted in the scaffolded + synth manifests;
HERMES_CLI_PATH asserted in both build configs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: chrfalch

packages/react-native/scripts/setup-apple-spm.js

@@ -535,8 +535,20 @@ function prepareLocalXcframeworkArtifacts(
     {};
   artifacts.React = {xcframeworkPath: localReactPath, url: ''};
 
-  // Look for ReactNativeDependencies and hermes-engine alongside or in cache
-  for (const name of ['ReactNativeDependencies', 'hermes-engine']) {
+  // Look for the deps binary, hermes, AND both headers companions alongside the
+  // React.xcframework or in the cache. The headers-only companions ship beside
+  // their binaries in the same tarball (ReactNativeHeaders beside React;
+  // ReactNativeDependenciesHeaders beside ReactNativeDependencies), so a
+  // `--artifacts <local React.xcframework>` slot extracted from the tarballs has
+  // them as siblings. They are REQUIRED (validateArtifactsCache /
+  // generate-spm-package both need them) — omitting them made the local slot
+  // report incomplete and forced a full Maven download, defeating "use directly".
+  for (const name of [
+    'ReactNativeHeaders',
+    'ReactNativeDependencies',
+    'ReactNativeDependenciesHeaders',
+    'hermes-engine',
+  ]) {
     const siblingPath = path.join(localXcfwDir, `${name}.xcframework`);
     const cachePath = path.join(
       defaultCacheDir(args.version ?? version, args.flavor),

packages/react-native/scripts/spm/__tests__/generate-spm-autolinking-test.js

@@ -272,6 +272,14 @@ describe('generateSynthPackageSwift', () => {
     );
   });
 
+  it('emits DEBUG/NDEBUG config-gated cxxSettings so Fabric C++ matches the prebuilt React.framework ABI', () => {
+    const result = generateSynthPackageSwift(baseSpec());
+    expect(result).toContain('.define("DEBUG", .when(configuration: .debug))');
+    expect(result).toContain(
+      '.define("NDEBUG", .when(configuration: .release))',
+    );
+  });
+
   it('depends on ReactNative via a fixed relative path (default synth depth)', () => {
     const result = generateSynthPackageSwift(baseSpec({hasReactDep: true}));
     expect(result).toContain(
@@ -1048,7 +1056,10 @@ describe('main() — autolinking plugin host exemption', () => {
     // The plugin-host dep: native sources present, but NO Package.swift.
     const expoDir = path.join(appRoot, 'node_modules', 'expo');
     fs.mkdirSync(path.join(expoDir, 'ios'), {recursive: true});
-    fs.writeFileSync(path.join(expoDir, 'ios', 'Expo.mm'), '// native source\n');
+    fs.writeFileSync(
+      path.join(expoDir, 'ios', 'Expo.mm'),
+      '// native source\n',
+    );
     if (withPlugin) {
       fs.writeFileSync(
         path.join(expoDir, 'react-native.config.js'),

packages/react-native/scripts/spm/__tests__/inject-spm-xcodeproj-test.js

@@ -147,6 +147,12 @@ describe('injectSpmIntoPbxproj — Tier 2 (build settings + phase)', () => {
     expect(text.match(/CLANG_CXX_LANGUAGE_STANDARD = "c\+\+20"/g)).toHaveLength(
       2,
     );
+    // HERMES_CLI_PATH points react-native-xcode.sh at the hermes-compiler npm
+    // package (no hermes-engine pod under SPM), injected into both configs.
+    expect(text.match(/HERMES_CLI_PATH = /g)).toHaveLength(2);
+    expect(text).toContain(
+      '$(REACT_NATIVE_PATH)/../hermes-compiler/hermesc/osx-bin/hermesc',
+    );
   });
 
   it('prepends the Sync SPM Autolinking build phase', () => {

packages/react-native/scripts/spm/__tests__/scaffold-package-swift-test.js

@@ -525,6 +525,12 @@ describe('emitScaffoldedPackageSwift', () => {
     expect(out).toContain('// Cache slot: 0.87.0-nightly-20260513-abc/debug');
   });
 
+  it('emits DEBUG/NDEBUG config-gated cxxSettings so Fabric C++ matches the prebuilt React.framework ABI', () => {
+    const out = emitScaffoldedPackageSwift(baseSpec());
+    expect(out).toContain('.define("DEBUG", .when(configuration: .debug))');
+    expect(out).toContain('.define("NDEBUG", .when(configuration: .release))');
+  });
+
   it('is fully declarative — no runtime discovery code, no Foundation import', () => {
     const out = emitScaffoldedPackageSwift(baseSpec());
     expect(out).not.toContain('import Foundation');

packages/react-native/scripts/spm/generate-spm-autolinking.js

@@ -336,6 +336,15 @@ const SKIP_DIRS_DEFAULT /*: ReadonlySet<string> */ = new Set([
 // like "<WRAPPER_ROOT_NAME>/Foo.mm" by following this link.
 const WRAPPER_ROOT_NAME = 'root';
 
+// The config-gated C++ defines the prebuilt React.framework is built with (see
+// packages/react-native/Package.swift). Autolinked Fabric C++ must compile with
+// the same NDEBUG state, else DebugStringConvertible's vtable / ShadowNode
+// layout diverges from a Release React.framework and the link fails.
+const REACT_CXX_CONFIG_DEFINES = [
+  '.define("DEBUG", .when(configuration: .debug))',
+  '.define("NDEBUG", .when(configuration: .release))',
+];
+
 // Marker the autolinker stamps onto every synth Package.swift it writes.
 // Files lacking this marker are treated as user-managed (self-managed) and
 // are referenced directly rather than wrapped — see findSelfManagedPackageDir.
@@ -932,6 +941,7 @@ function generateAutolinkedPackageSwift(
             name: "${t.name}",
             dependencies: [${reactProductDeps()}],
             path: "${t.path}",${excludeLine}${publicHeadersLine}${resourcesLine}
+            cxxSettings: [${REACT_CXX_CONFIG_DEFINES.join(', ')}],
             linkerSettings: [.linkedFramework("UIKit"), .linkedFramework("Foundation"), .linkedFramework("CoreGraphics")]
         )`;
   });
@@ -1129,17 +1139,19 @@ function generateSynthPackageSwift(spec /*: SynthPackageSpec */) /*: string */ {
   // `.headerSearchPath(...)` entries from the podspec — first-class
   // directives keep SPM's diagnostics meaningful (clang reports the
   // dep-relative path on miss). React headers need no paths at all.
-  const headerSearchPathDirectives = headerSearchPaths
-    .map(p => `.headerSearchPath("${p}")`)
-    .join(', ');
+  const headerSearchPathList = headerSearchPaths.map(
+    p => `.headerSearchPath("${p}")`,
+  );
   const cSettingsLine =
-    headerSearchPaths.length > 0
-      ? `\n            cSettings: [${headerSearchPathDirectives}],`
-      : '';
-  const cxxSettingsLine =
-    headerSearchPaths.length > 0
-      ? `\n            cxxSettings: [${headerSearchPathDirectives}],`
+    headerSearchPathList.length > 0
+      ? `\n            cSettings: [${headerSearchPathList.join(', ')}],`
       : '';
+  // ALWAYS emit the config-gated C++ defines (even with no header paths): a
+  // Fabric C++ target must compile with the same NDEBUG state as the prebuilt
+  // React.framework, else DebugStringConvertible's vtable / ShadowNode layout
+  // diverges and a Release build fails to link. Mirrors Package.swift.
+  const cxxEntries = [...REACT_CXX_CONFIG_DEFINES, ...headerSearchPathList];
+  const cxxSettingsLine = `\n            cxxSettings: [${cxxEntries.join(', ')}],`;
 
   return `// swift-tools-version: 6.0
 // AUTO-GENERATED by scripts/generate-spm-autolinking.js – do not edit manually.

packages/react-native/scripts/spm/generate-spm-xcodeproj.js

@@ -913,6 +913,18 @@ function mergeReactBuildSettings(
   const scalars = [
     {key: 'CLANG_CXX_LANGUAGE_STANDARD', value: '"c++20"'},
     {key: 'REACT_NATIVE_PATH', value: quoteIfNeeded(reactNativePath)},
+    // Under SwiftPM there is no hermes-engine pod, so react-native-xcode.sh's
+    // fallback ($PODS_ROOT/hermes-engine/destroot/bin/hermesc) resolves to a
+    // non-existent "/hermes-engine/..." and the Release JS→Hermes bundling
+    // fails. Point HERMES_CLI_PATH at the hermes-compiler npm package's host
+    // hermesc (sibling of react-native in node_modules). react-native-xcode.sh
+    // honors an already-set HERMES_CLI_PATH before its pod fallback; the
+    // ensureScalarField below leaves any user-provided value untouched.
+    {
+      key: 'HERMES_CLI_PATH',
+      value:
+        '"$(REACT_NATIVE_PATH)/../hermes-compiler/hermesc/osx-bin/hermesc"',
+    },
   ];
   // Re-locate the buildSettings dict before each edit (offsets shift).
   const dict = () => {

packages/react-native/scripts/spm/scaffold-package-swift.js

@@ -97,7 +97,10 @@ const {log} = makeLogger('scaffold-package-swift');
 // pure-RN; folly/glog/boost/... now come from the deps sidecar);
 // publicHeadersPath falls back to "." for root-level-source podspecs
 // (`s.source_files = "*.{h,m,mm}"`) instead of SPM's nonexistent `include/`.
-const SCAFFOLDER_VERSION = 18;
+// v19: scaffolded C++ targets carry DEBUG/NDEBUG config defines so their Fabric
+// ABI matches the prebuilt React.framework (Release strips DebugStringConvertible
+// under NDEBUG). Bumped so existing scaffolds regenerate with the defines.
+const SCAFFOLDER_VERSION = 19;
 const SCAFFOLDER_VERSION_LINE_RE = /^\/\/ AUTO-SCAFFOLDED-VERSION: (\d+)$/m;
 
 const AUTOGEN_MARKER =
@@ -110,6 +113,15 @@ const AUTOGEN_MARKER =
 // target (cSettings + cxxSettings) to reproduce that ambient import. The
 // `__OBJC__` guard makes it inert for plain C/C++ sources, and UIKit is
 // `__has_include`-guarded for platforms that lack it.
+// The config-gated C++ defines the prebuilt React.framework is built with (see
+// packages/react-native/Package.swift). Fabric C++ in autolinked deps must
+// compile with the SAME NDEBUG state or its DebugStringConvertible / ShadowNode
+// ABI diverges from the Release React.framework and the link fails.
+const REACT_CXX_CONFIG_DEFINES = [
+  '.define("DEBUG", .when(configuration: .debug))',
+  '.define("NDEBUG", .when(configuration: .release))',
+];
+
 const SCAFFOLD_PREFIX_HEADER = 'react-native-spm-prefix.h';
 const SCAFFOLD_PREFIX_HEADER_CONTENTS = `// AUTO-SCAFFOLDED by react-native spm scaffold — mirrors CocoaPods' default
 // prefix header so ObjC sources that rely on an implicit Foundation/UIKit
@@ -606,6 +618,12 @@ function emitScaffoldedPackageSwift(
       ...(customFlagsCxx.length > 0
         ? [`.unsafeFlags([${customFlagsCxx.join(', ')}])`]
         : []),
+      // Match the prebuilt React.framework's config-gated C++ ABI. NDEBUG in
+      // Release strips DebugStringConvertible's vtable (and shifts the
+      // ShadowNode layout that inherits it), so a Fabric C++ target compiled
+      // WITHOUT NDEBUG fails to link against a Release React.framework. Mirrors
+      // packages/react-native/Package.swift's own C++ targets.
+      ...REACT_CXX_CONFIG_DEFINES,
     ].filter(e => e.length > 0),
   );