feat(ci): recompose upstream Hermes xcframework with macOS slice

Saadnajmi · claude · Saadnajmi · commit 3b5be70dad22 · 2026-04-17T17:37:26.000-07:00
Instead of building Hermes from source (~90 min), download the
upstream tarball from Maven, extract frameworks from the universal
xcframework, add the standalone macOS framework, and recompose
a new xcframework that includes all platforms.

Build-from-source is kept as a fallback when no upstream tarball
is available (e.g. Maven is down).

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/microsoft-resolve-hermes.yml b/.github/workflows/microsoft-resolve-hermes.yml
@@ -7,10 +7,11 @@ jobs:
   resolve-hermes:
     name: "Resolve Hermes"
     runs-on: macos-15
-    timeout-minutes: 10
+    timeout-minutes: 15
     outputs:
       hermes-commit: ${{ steps.resolve.outputs.hermes-commit }}
       cache-hit: ${{ steps.cache.outputs.cache-hit }}
+      recomposed: ${{ steps.recompose.outputs.recomposed }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -26,7 +27,87 @@ jobs:
       - name: Install npm dependencies
         run: yarn install
 
+      - name: Download upstream Hermes tarball
+        id: download
+        working-directory: packages/react-native
+        run: |
+          node -e "
+            const {downloadUpstreamHermesTarball} = require('./scripts/ios-prebuild/macosVersionResolver');
+            downloadUpstreamHermesTarball('Debug').then(r => {
+              require('fs').writeFileSync('/tmp/hermes-download-result.json', JSON.stringify(r));
+            });
+          "
+          RESULT=$(cat /tmp/hermes-download-result.json)
+          if [ "$RESULT" != "null" ]; then
+            TARBALL=$(node -e "console.log(JSON.parse(process.argv[1]).tarballPath)" "$RESULT")
+            VERSION=$(node -e "console.log(JSON.parse(process.argv[1]).version)" "$RESULT")
+            echo "tarball=$TARBALL" >> "$GITHUB_OUTPUT"
+            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+            echo "Downloaded upstream Hermes tarball for version $VERSION"
+          else
+            echo "No upstream tarball available"
+          fi
+
+      - name: Recompose xcframework with macOS slice
+        id: recompose
+        if: steps.download.outputs.tarball != ''
+        run: |
+          TARBALL="${{ steps.download.outputs.tarball }}"
+
+          # Extract tarball
+          mkdir -p hermes-destroot
+          tar -xzf "$TARBALL" -C hermes-destroot --strip-components=2
+
+          echo "=== Upstream tarball contents ==="
+          ls -la hermes-destroot/Library/Frameworks/
+
+          # Collect existing frameworks from the universal xcframework
+          XCFW="hermes-destroot/Library/Frameworks/universal/hermes.xcframework"
+          FRAMEWORKS=()
+          for fw in "$XCFW"/*/hermes.framework; do
+            if [ -d "$fw" ]; then
+              echo "Found slice: $fw"
+              FRAMEWORKS+=(-framework "$fw")
+            fi
+          done
+
+          # Add standalone macOS framework
+          MAC_FW="hermes-destroot/Library/Frameworks/macosx/hermes.framework"
+          if [ -d "$MAC_FW" ]; then
+            echo "Found standalone macOS slice: $MAC_FW"
+            FRAMEWORKS+=(-framework "$MAC_FW")
+          else
+            echo "::error::Upstream tarball missing macosx/hermes.framework"
+            echo "recomposed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Remove old xcframework and create new one with macOS included
+          rm -rf "$XCFW"
+          echo "Creating new universal xcframework with ${#FRAMEWORKS[@]} frameworks..."
+          xcodebuild -create-xcframework "${FRAMEWORKS[@]}" \
+            -output "$XCFW" \
+            -allow-internal-distribution
+
+          # Clean up standalone macOS dir (now included in universal)
+          rm -rf hermes-destroot/Library/Frameworks/macosx
+
+          echo "=== Recomposed xcframework ==="
+          ls -la "$XCFW"/
+
+          echo "recomposed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Upload recomposed Hermes artifacts
+        if: steps.recompose.outputs.recomposed == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: hermes-artifacts
+          path: hermes-destroot
+          retention-days: 30
+
+      # Fallback: resolve Hermes commit for build-from-source
       - name: Resolve Hermes commit at merge base
+        if: steps.recompose.outputs.recomposed != 'true'
         id: resolve
         working-directory: packages/react-native
         run: |
@@ -35,14 +116,15 @@ jobs:
           echo "Resolved Hermes commit: $COMMIT"
 
       - name: Restore Hermes cache
+        if: steps.recompose.outputs.recomposed != 'true'
         id: cache
         uses: actions/cache/restore@v4
         with:
           key: hermes-v1-${{ steps.resolve.outputs.hermes-commit }}-Debug
           path: hermes-destroot
 
       - name: Upload cached Hermes artifacts
-        if: steps.cache.outputs.cache-hit == 'true'
+        if: steps.recompose.outputs.recomposed != 'true' && steps.cache.outputs.cache-hit == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: hermes-artifacts
@@ -51,7 +133,7 @@ jobs:
 
   build-hermesc:
     name: "Build hermesc"
-    if: ${{ needs.resolve-hermes.outputs.cache-hit != 'true' }}
+    if: ${{ needs.resolve-hermes.outputs.recomposed != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
     needs: resolve-hermes
     runs-on: macos-15
     timeout-minutes: 30
@@ -92,7 +174,7 @@ jobs:
 
   build-hermes-slice:
     name: "Hermes ${{ matrix.slice }}"
-    if: ${{ needs.resolve-hermes.outputs.cache-hit != 'true' }}
+    if: ${{ needs.resolve-hermes.outputs.recomposed != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
     needs: [resolve-hermes, build-hermesc]
     runs-on: macos-15
     timeout-minutes: 45
@@ -160,7 +242,7 @@ jobs:
 
   assemble-hermes:
     name: "Assemble Hermes xcframework"
-    if: ${{ needs.resolve-hermes.outputs.cache-hit != 'true' }}
+    if: ${{ needs.resolve-hermes.outputs.recomposed != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
     needs: [resolve-hermes, build-hermes-slice]
     runs-on: macos-15
     timeout-minutes: 15
diff --git a/packages/react-native/scripts/ios-prebuild/macosVersionResolver.js b/packages/react-native/scripts/ios-prebuild/macosVersionResolver.js
@@ -184,6 +184,52 @@ async function getLatestStableVersionFromNPM() /*: Promise<string> */ {
   return json.version;
 }
 
+/**
+ * Downloads the upstream Hermes tarball from Maven for the mapped
+ * upstream version. Returns the tarball path and version on success,
+ * or null if no tarball is available.
+ *
+ * The caller is responsible for extracting and recomposing the
+ * xcframework (e.g. adding the macOS slice to the universal).
+ */
+async function downloadUpstreamHermesTarball(
+  buildType /*: string */ = 'Debug',
+) /*: Promise<?{| tarballPath: string, version: string |}> */ {
+  const packageJsonPath = path.resolve(__dirname, '..', '..', 'package.json');
+  const version = findMatchingHermesVersion(packageJsonPath);
+  if (version == null) {
+    macosLog('No upstream version found, cannot download tarball');
+    return null;
+  }
+
+  const mavenUrl = `https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/${version}/react-native-artifacts-${version}-hermes-ios-${buildType.toLowerCase()}.tar.gz`;
+
+  macosLog(
+    `Downloading upstream Hermes tarball (${version}) from ${mavenUrl}...`,
+  );
+
+  try {
+    const response /*: Response */ = await fetch(mavenUrl);
+    if (!response.ok) {
+      macosLog(
+        `Tarball not found: ${response.status} ${response.statusText}`,
+      );
+      return null;
+    }
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-'));
+    const tarballPath = path.join(tmpDir, 'hermes-ios.tar.gz');
+    const buffer = await response.arrayBuffer();
+    fs.writeFileSync(tarballPath, Buffer.from(buffer));
+
+    macosLog(`Downloaded upstream Hermes tarball to ${tarballPath}`);
+    return {tarballPath, version};
+  } catch (e) {
+    macosLog(`Error downloading tarball: ${e.message}`);
+    return null;
+  }
+}
+
 function abort(message /*: string */) {
   macosLog(message, 'error');
   throw new Error(message);
@@ -194,4 +240,5 @@ module.exports = {
   hermesCommitAtMergeBase,
   findVersionAtMergeBase,
   getLatestStableVersionFromNPM,
+  downloadUpstreamHermesTarball,
 };
