feat(spm): automatic Debug/Release flavor swap for SwiftPM

chrfalch · claude · chrfalch · commit 5e4e75906c85 · 2026-07-08T21:19:45.000+02:00
RN ships flavored prebuilt binaries — debug React/hermesvm/ReactNativeDependencies
carry the dev experience (dev menu, assertions, RN_DEBUG_STRING_CONVERTIBLE),
release strips them — so a Debug build must embed debug binaries and a
Release/archive the release ones. SwiftPM binaryTargets can't branch on the build
configuration, so mirror the CocoaPods React-Core-prebuilt swap
(replace-rncore-version.js):

- `spm add` now downloads BOTH flavors up front (best-effort) so the swap never
  needs the network mid-build.
- New `swap-flavor` action + swap-flavor.js: reads the Xcode build env
  ($CONFIGURATION / $BUILT_PRODUCTS_DIR / $PLATFORM_NAME), slice-matches the
  target flavor's React / ReactNativeDependencies / hermesvm frameworks from the
  cache slot, and rsyncs them over the SwiftPM-copied frameworks in
  BUILT_PRODUCTS_DIR before Link. Idempotent, best-effort (never fatal). Resolves
  the cache slot via a single-level readlink (not realpath) so a locally-built
  React.xcframework symlinked into the slot doesn't send resolution out of the
  slot and under-swap.
- The generated build phase invokes it on every build (no-op in the scheme
  pre-action, where BUILT_PRODUCTS_DIR isn't populated yet).

Verified on the sim BOTH directions (hash-compared against the slot binaries):
add-debug→Release build ships release; add-release→Debug build ships debug; all
three frameworks swapped. Unit tests cover platform→slice mapping (incl. Mac
Catalyst) and the swap at both the top-level and PackageFrameworks layouts.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/react-native/scripts/setup-apple-spm.js b/packages/react-native/scripts/setup-apple-spm.js
@@ -123,6 +123,7 @@ const VALID_ACTIONS = new Set([
   'codegen',
   'download',
   'scaffold',
+  'swap-flavor',
 ]);
 
 /*::
@@ -297,7 +298,7 @@ function promptYesNo(
 function resolveAction(
   requestedAction /*: SetupArgs['action'] */,
   appRoot /*: string */,
-) /*: 'add' | 'update' | 'deinit' | 'sync' | 'codegen' | 'download' | 'scaffold' */ {
+) /*: 'add' | 'update' | 'deinit' | 'sync' | 'codegen' | 'download' | 'scaffold' | 'swap-flavor' */ {
   if (requestedAction != null) {
     return requestedAction;
   }
@@ -996,6 +997,28 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
     log(`Project root (package.json): ${displayPath(projectRoot)}`);
   }
 
+  // Build-time flavor swap (invoked by the generated build phase). Kept early
+  // and dependency-free — no version resolution, no network — because it runs
+  // on EVERY Xcode build. Reads the Xcode build env for the target flavor +
+  // products dir.
+  if (action === 'swap-flavor') {
+    const {swapFlavorFrameworks} = require('./spm/swap-flavor');
+    try {
+      swapFlavorFrameworks({
+        appRoot,
+        configuration: process.env.CONFIGURATION,
+        builtProductsDir: process.env.BUILT_PRODUCTS_DIR,
+        platformName: process.env.PLATFORM_NAME,
+        isMacCatalyst: process.env.IS_MACCATALYST === 'YES',
+        logger: {log},
+      });
+    } catch (e) {
+      // Non-fatal: a flavor-swap failure must not break the build.
+      logError(`swap-flavor failed: ${e.message}`);
+    }
+    return;
+  }
+
   if (action === 'deinit') {
     const xcodeprojPath =
       args.xcodeprojPath != null
@@ -1190,6 +1213,28 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
       process.exitCode = 1;
       return;
     }
+
+    // Pre-fetch the OTHER flavor's slot so the build-time `swap-flavor` phase
+    // can switch debug↔release without touching the network (mirrors CocoaPods
+    // downloading both flavors up front). Best-effort: a Debug-only workflow
+    // still builds if the release slot can't be fetched now — the swap just
+    // logs and leaves the resolved flavor in place. Honors --download skip.
+    if (action === 'add' || action === 'update') {
+      const otherFlavor = args.flavor === 'release' ? 'debug' : 'release';
+      try {
+        const otherArgs = {...args, flavor: otherFlavor};
+        await ensureArtifacts(
+          otherArgs,
+          version,
+          prepareLocalXcframeworkArtifacts(otherArgs, appRoot, version),
+        );
+      } catch (e) {
+        logError(
+          `Could not pre-fetch the ${otherFlavor} flavor for build-time swapping (${e.message}). ` +
+            `A ${otherFlavor}-configuration build will need it — re-run with network, or \`spm download --flavor ${otherFlavor}\`.`,
+        );
+      }
+    }
   } else {
     log(`Remote ReactNative package: ${remote.url} @ ${remote.version}`);
   }
diff --git a/packages/react-native/scripts/spm/__doc__/spm-scripts.md b/packages/react-native/scripts/spm/__doc__/spm-scripts.md
@@ -130,7 +130,7 @@ accepts kebab-case equivalents (e.g. `--skip-codegen`).
 | Option | Description |
 |---|---|
 | `--version <ver>` | RN version (default: from package.json) |
-| `--flavor <debug\|release>` | Artifact flavor (default: debug) |
+| `--flavor <debug\|release>` | Initial artifact flavor to resolve (default: debug). Both flavors are fetched at `add`; the embedded flavor then auto-matches the Xcode build configuration — see below |
 | `--yes` | Skip the dirty-pbxproj confirmation prompt |
 | `--xcodeproj <path>` | [add] Which `.xcodeproj` to inject into (when several exist) |
 | `--productName <name>` | [add] Which app target to inject into (when several exist) |
@@ -139,6 +139,24 @@ accepts kebab-case equivalents (e.g. `--skip-codegen`).
 | `--download <auto\|skip\|force>` | [advanced] Artifact download policy (default: auto) |
 | `--skipCodegen` | [advanced] Skip the codegen step |
 
+### Debug/Release flavor is automatic
+
+React Native ships **flavored** prebuilt binaries: the *debug* `React.framework`
+(and `hermesvm` / `ReactNativeDependencies`) carry the dev experience — dev menu,
+assertions, `RN_DEBUG_STRING_CONVERTIBLE` — while *release* strips them for
+production. A Debug build must embed the debug binaries and a Release/archive the
+release ones.
+
+SwiftPM `binaryTarget`s can't branch on the build configuration, so — mirroring
+the CocoaPods `React-Core-prebuilt` swap (`replace-rncore-version.js`) — `spm add`
+downloads **both** flavors, and a generated build phase (`react-native spm
+swap-flavor`) overwrites the SwiftPM-copied `React` / `ReactNativeDependencies` /
+`hermesvm` frameworks in `BUILT_PRODUCTS_DIR` with the slice matching
+`$CONFIGURATION`, before Link. It runs on every build, is idempotent, and works
+under both Xcode and `xcodebuild`. No manual step: build Debug → debug binaries,
+build Release/archive → release binaries. (`--flavor` only sets which flavor is
+resolved first; the swap corrects the embedded binaries per build.)
+
 ## What to commit
 
 | Path | Commit? | Why |
diff --git a/packages/react-native/scripts/spm/__tests__/swap-flavor-test.js b/packages/react-native/scripts/spm/__tests__/swap-flavor-test.js
@@ -0,0 +1,180 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @noflow
+ */
+
+'use strict';
+
+const {matchSlice, swapFlavorFrameworks} = require('../swap-flavor');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const plist = require('plist');
+
+// Build a minimal <name>.xcframework with the given slices, each carrying a
+// <name>.framework whose binary contains `content` (to assert what got copied).
+function mkXcframework(dir, name, slices, content) {
+  fs.mkdirSync(dir, {recursive: true});
+  const available = slices.map(s => ({
+    LibraryIdentifier: s.id,
+    LibraryPath: `${name}.framework`,
+    SupportedPlatform: s.platform,
+    SupportedArchitectures: ['arm64'],
+    ...(s.variant ? {SupportedPlatformVariant: s.variant} : {}),
+  }));
+  fs.writeFileSync(
+    path.join(dir, 'Info.plist'),
+    plist.build({
+      AvailableLibraries: available,
+      CFBundlePackageType: 'XFWK',
+      XCFrameworkFormatVersion: '1.0',
+    }),
+  );
+  for (const s of slices) {
+    const fw = path.join(dir, s.id, `${name}.framework`);
+    fs.mkdirSync(fw, {recursive: true});
+    fs.writeFileSync(path.join(fw, name), content);
+  }
+}
+
+describe('matchSlice', () => {
+  let tmp, xcfw;
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'swap-match-'));
+    xcfw = path.join(tmp, 'React.xcframework');
+    mkXcframework(
+      xcfw,
+      'React',
+      [
+        {id: 'ios-arm64', platform: 'ios'},
+        {
+          id: 'ios-arm64_x86_64-simulator',
+          platform: 'ios',
+          variant: 'simulator',
+        },
+        {
+          id: 'ios-arm64_x86_64-maccatalyst',
+          platform: 'ios',
+          variant: 'maccatalyst',
+        },
+        {id: 'tvos-arm64', platform: 'tvos'},
+      ],
+      'x',
+    );
+  });
+  afterEach(() => fs.rmSync(tmp, {recursive: true, force: true}));
+
+  it('maps iphonesimulator to the ios+simulator slice', () => {
+    expect(matchSlice(xcfw, 'iphonesimulator', false)).toBe(
+      'ios-arm64_x86_64-simulator',
+    );
+  });
+  it('maps iphoneos to the ios (no-variant) slice', () => {
+    expect(matchSlice(xcfw, 'iphoneos', false)).toBe('ios-arm64');
+  });
+  it('maps Mac Catalyst explicitly (macosx PLATFORM_NAME + variant)', () => {
+    expect(matchSlice(xcfw, 'macosx', true)).toBe(
+      'ios-arm64_x86_64-maccatalyst',
+    );
+  });
+  it('returns null for an unknown platform', () => {
+    expect(matchSlice(xcfw, 'watchos', false)).toBeNull();
+  });
+});
+
+describe('swapFlavorFrameworks', () => {
+  let tmp, appRoot, builtProducts;
+  const read = p => fs.readFileSync(p, 'utf8');
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'swap-fw-'));
+    // Cache slots: debug + release, each with a React.framework binary tagged
+    // by flavor so we can assert which one landed.
+    for (const flavor of ['debug', 'release']) {
+      mkXcframework(
+        path.join(tmp, 'cache', '1.0', flavor, 'React.xcframework'),
+        'React',
+        [
+          {
+            id: 'ios-arm64_x86_64-simulator',
+            platform: 'ios',
+            variant: 'simulator',
+          },
+        ],
+        `REACT-${flavor}`,
+      );
+    }
+    // App: build/xcframeworks/React.xcframework -> the DEBUG slot (as `spm add`
+    // --flavor debug would leave it).
+    appRoot = path.join(tmp, 'app');
+    const links = path.join(appRoot, 'build', 'xcframeworks');
+    fs.mkdirSync(links, {recursive: true});
+    fs.symlinkSync(
+      path.join(tmp, 'cache', '1.0', 'debug', 'React.xcframework'),
+      path.join(links, 'React.xcframework'),
+    );
+    // SPM-copied (debug) framework in PackageFrameworks.
+    builtProducts = path.join(tmp, 'products');
+    const pf = path.join(builtProducts, 'PackageFrameworks', 'React.framework');
+    fs.mkdirSync(pf, {recursive: true});
+    fs.writeFileSync(path.join(pf, 'React'), 'REACT-debug');
+  });
+  afterEach(() => fs.rmSync(tmp, {recursive: true, force: true}));
+
+  const embedded = () =>
+    read(
+      path.join(builtProducts, 'PackageFrameworks', 'React.framework', 'React'),
+    );
+
+  it('swaps the copied debug framework to release for a Release build', () => {
+    swapFlavorFrameworks({
+      appRoot,
+      configuration: 'Release',
+      builtProductsDir: builtProducts,
+      platformName: 'iphonesimulator',
+    });
+    expect(embedded()).toBe('REACT-release');
+  });
+
+  it('leaves debug in place for a Debug build (idempotent)', () => {
+    swapFlavorFrameworks({
+      appRoot,
+      configuration: 'Debug',
+      builtProductsDir: builtProducts,
+      platformName: 'iphonesimulator',
+    });
+    expect(embedded()).toBe('REACT-debug');
+  });
+
+  it('swaps a framework at the BUILT_PRODUCTS_DIR top level (real SPM binaryTarget layout)', () => {
+    // SPM copies binaryTarget frameworks to <BUILT_PRODUCTS_DIR>/<F>.framework,
+    // not PackageFrameworks/. Put it there and confirm the swap finds it.
+    const topFw = path.join(builtProducts, 'React.framework');
+    fs.mkdirSync(topFw, {recursive: true});
+    fs.writeFileSync(path.join(topFw, 'React'), 'REACT-debug');
+    swapFlavorFrameworks({
+      appRoot,
+      configuration: 'Release',
+      builtProductsDir: builtProducts,
+      platformName: 'iphonesimulator',
+    });
+    expect(read(path.join(topFw, 'React'))).toBe('REACT-release');
+  });
+
+  it('no-ops when the products dir does not exist (pre-action)', () => {
+    expect(() =>
+      swapFlavorFrameworks({
+        appRoot,
+        configuration: 'Release',
+        builtProductsDir: path.join(tmp, 'nope'),
+        platformName: 'iphonesimulator',
+      }),
+    ).not.toThrow();
+    expect(embedded()).toBe('REACT-debug');
+  });
+});
diff --git a/packages/react-native/scripts/spm/generate-spm-xcodeproj.js b/packages/react-native/scripts/spm/generate-spm-xcodeproj.js
@@ -260,6 +260,21 @@ function buildSyncAutolinkingScript(
 ) /*: string */ {
   return `set -euo pipefail
 
+# Swap the flavored framework binaries (React / ReactNativeDependencies /
+# hermesvm) to match the Xcode build configuration. SwiftPM can't branch a
+# binaryTarget on \$CONFIGURATION, so — mirroring the CocoaPods
+# React-Core-prebuilt swap (replace-rncore-version.js) — we overwrite the
+# SPM-copied frameworks in \$BUILT_PRODUCTS_DIR/PackageFrameworks with the
+# correct-flavor slices, before Link. Runs on EVERY build (a config flip changes
+# no sync input) and is timing-robust: it operates on the ALREADY-copied
+# frameworks, so it doesn't race SPM package resolution. A no-op in the scheme
+# pre-action (\$BUILT_PRODUCTS_DIR unset / nothing copied yet) and when already
+# the right flavor. Non-fatal.
+if command -v npx >/dev/null 2>&1 && [ -n "\${BUILT_PRODUCTS_DIR:-}" ]; then
+  ( cd "$SRCROOT" && npx react-native spm swap-flavor ) \\
+    || echo "warning: 'react-native spm swap-flavor' failed; build may link the add-time flavor"
+fi
+
 STAMP="$SRCROOT/build/generated/autolinking/.spm-sync-stamp"
 STALE=0
 
diff --git a/packages/react-native/scripts/spm/swap-flavor.js b/packages/react-native/scripts/spm/swap-flavor.js
