feat: build React Native macOS with Swift Package Manager by Saadnajmi · Pull Request #2815 · microsoft/react-native-macos

Saadnajmi · 2026-01-17T03:48:37Z

Summary

Extends the Hermes build scripts to include macOS slices in the universal xcframework, and adds macOS support to the Swift Package Manager build system.

Currently, Hermes builds a standalone macOS .framework via build-mac-framework.sh but does not include it in the universal .xcframework used by SPM. This means SPM consumers cannot target macOS. This PR fixes that by adding macosx as a platform in build-ios-framework.sh, so the macOS slice is built alongside iOS, visionOS, tvOS, and catalyst — and included in the universal xcframework.

This mirrors the upstream Hermes changes:

fix: include macOS slice in universal hermes xcframework facebook/hermes#1958 (static_h — full consolidation)

Commit 1: SPM macOS support

Add .macOS(.v14) platform to Package.swift
Create React-RCTUIKit as its own SPM module with conditional UIKit/AppKit linking
Port findMatchingHermesVersion and hermesCommitAtMergeBase from Ruby to JS for Hermes version resolution
Add macOS platform and destination to prebuild CLI
Link RCTUIKit and macOS view platform headers in setup

Commit 2: Include macOS slice in Hermes xcframework

Add "macosx" to create_universal_framework and create_framework in build-ios-framework.sh
Add macosx cases to get_architecture (x86_64;arm64) and get_deployment_target
Make HERMES_PATH overridable via env var in build-apple-framework.sh

Commit 3: CI jobs

Add microsoft-build-spm.yml reusable workflow with two stages:
- Build Hermes: Builds Hermes from source on macos-15 (includes the macOS slice)
- Build SPM: Uses the Hermes artifact to build SPM for ios, macos, and visionos on macos-26
Wire into PR gate in microsoft-pr.yml
Add cmake-version input to microsoft-setup-toolchain to allow skipping CMake installation
Add visionos/visionos-simulator as supported platforms in the ios-prebuild CLI

Test plan

CI: Build Hermes from source with macOS slice
CI: SPM builds pass for iOS, macOS, visionOS
CocoaPods builds verified locally for iOS, macOS, visionOS

🤖 Generated with Claude Code

changeset-bot · 2026-03-23T03:20:04Z

⚠️ No Changeset found

Latest commit: 21f812c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

## Summary Fixes compilation errors that block macOS SPM builds, helping unblock #2815. - **RCTLinkingManager**: combined iOS and macOS implementations into a single file using `#if TARGET_OS_OSX` guards. Added missing `NativeLinkingManagerSpec` conformance (`openSettings`, `sendIntent`, `getTurboModule`), removed unused import, deleted the `macos/` overlay directory, and cleaned up the podspec - **RCTCursor.m**: replaced `Foundation.h` + conditional `AppKit.h` with `RCTUIKit` umbrella header - **RCTViewComponentView.mm**: removed duplicate `cursor` property check introduced during merge ## Test plan - [x] macOS SPM build passes (verified on `feature/spm-macos-support` — zero errors from these files) - [ ] Verify iOS build is not regressed 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Saadnajmi · 2026-04-08T23:51:09Z

packages/react-native/Package.swift

+    // [macOS] Platform-specific framework linking for targets that need UIKit (iOS/visionOS) vs AppKit (macOS)
+    var conditionalLinkerSettings: [LinkerSetting] = linkerSettings
+    if name == "React-graphics-Apple" || name == "React-RCTUIKit" {
+      conditionalLinkerSettings.append(.linkedFramework("UIKit", .when(platforms: [.iOS, .visionOS])))
+      conditionalLinkerSettings.append(.linkedFramework("AppKit", .when(platforms: [.macOS])))
+    }
+    // macOS]


Can we remove if we handle higher up?

.github/workflows/microsoft-build-spm.yml

packages/react-native/scripts/ios-prebuild/hermes.js

tido64 · 2026-04-09T12:56:20Z

packages/react-native/scripts/ios-prebuild/hermes.js

+    const tarballPath = path.join(artifactsPath, tarballName);
+    hermesLog('Creating Hermes tarball from build output...');
+    execSync(`tar -czf "${tarballPath}" -C "${hermesDir}" destroot`, {
+      stdio: 'inherit',


Consider creating { stdio: "inherit" } once and reuse it (I see it being created at least 4 times in this function alone).

packages/react-native/scripts/ios-prebuild/reactNativeDependencies.js

- Add macOS and visionOS platforms to ios-prebuild CLI and type definitions - Build Hermes from source at the merge base with facebook/react-native when no prebuilt artifacts are available (main branch / 1000.0.0) - Fix host hermesc cmake build by setting CMAKE_OSX_DEPLOYMENT_TARGET to prevent -Werror=unguarded-availability-new failures in LLVM config checks - Map ReactNativeDependencies version to upstream RN via peerDependencies, with fallback to merge base version or latest stable release for main branch - Conditionally include macOS-specific platform view sources in Package.swift using #if os(macOS) to avoid compiling macOS C++ on iOS/visionOS - Platform-conditional UIKit/AppKit framework linking via platformLinkerSettings Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Make HERMES_PATH overridable via environment variable so CI can point to a separately cloned Hermes repo - Add CMAKE_OSX_DEPLOYMENT_TARGET to build_host_hermesc to fix -Werror=unguarded-availability-new failures in LLVM cmake checks - Add macOS deployment target support via get_mac_deployment_target Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add microsoft-build-spm.yml with 4-stage pipeline: 1. resolve-hermes: find Hermes commit, check cache 2. build-hermesc + build-hermes-slice (5x parallel): build from source 3. assemble-hermes: create universal xcframework, save cache 4. build-spm (ios/macos/visionos): build SPM packages The assembled Hermes xcframework is cached by commit hash, so ~95% of CI runs skip the entire Hermes build and go straight to SPM builds. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Rename workflow to "Build SwiftPM" (tido64) - Replace shallow clone + fetch with actions/checkout for Hermes (tido64) - Use efficient git init + fetch pattern in buildFromHermesCommit (tido64) - Extract reusable build env object in hermes.js (tido64) - Move macOS version resolution to fork-only macosVersionResolver.js (tido64) - Replace platformLinkerSettings with #if os(macOS) in Package.swift (Saad) - Revert CMAKE_OSX_DEPLOYMENT_TARGET from build-apple-framework.sh (Saad) - Add // [macOS] tag to os require in hermes.js (tido64) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/react-native/scripts/ios-prebuild/reactNativeDependencies.js

Saadnajmi · 2026-04-10T01:35:13Z

packages/react-native/sdks/hermes-engine/utils/build-apple-framework.sh

 BUILD_TYPE=${BUILD_TYPE:-Debug}

-HERMES_PATH="$CURR_SCRIPT_DIR/.."
+HERMES_PATH=${HERMES_PATH:-"$CURR_SCRIPT_DIR/.."}


Add a comment why we need this change

tido64

I've only reviewed the code as this can't really be tested atm.

Saadnajmi · 2026-04-14T18:52:46Z

.github/workflows/microsoft-build-spm.yml

+        with:
+          name: hermes-artifacts
+          path: hermes/destroot
+          retention-days: 1


Do we want more...?

Saadnajmi · 2026-04-14T19:06:33Z

packages/react-native/scripts/ios-prebuild/hermes.js

+    const sourceType = await hermesSourceType(
+      resolvedVersion,
+      buildType,
+      allowBuildFromSource,


// [macOS] tag here

Saadnajmi · 2026-04-14T19:06:47Z

packages/react-native/scripts/ios-prebuild/hermes.js

  | 'local_prebuilt_tarball'
  | 'download_prebuild_tarball'
  | 'download_prebuilt_nightly_tarball'
+  | 'build_from_hermes_commit'


// [macOS] tag here

Saadnajmi · 2026-04-14T19:08:00Z

packages/react-native/scripts/ios-prebuild/hermes.js

+ *
+ * @param version - The resolved version string
+ * @param buildType - Debug or Release
+ * @param allowBuildFromSource - If true (macOS main branch), fall back to BUILD_FROM_HERMES_COMMIT
+ *   when no prebuilt artifacts exist. If false, fall back to nightly download (original behavior).


Remove the comment since it's not upstream

Saadnajmi · 2026-04-14T19:08:16Z

packages/react-native/scripts/ios-prebuild/hermes.js

 async function hermesSourceType(
  version /*: string */,
  buildType /*: BuildFlavor */,
+  allowBuildFromSource /*: boolean */ = false,


Add a // [macOS] tag here

Saadnajmi · 2026-04-14T19:08:30Z

packages/react-native/scripts/ios-prebuild/hermes.js

    case HermesEngineSourceTypes.DOWNLOAD_PREBUILT_NIGHTLY_TARBALL:
      return downloadPrebuiltNightlyTarball(version, buildType, artifactsPath);
+    case HermesEngineSourceTypes.BUILD_FROM_HERMES_COMMIT: // [macOS]
+      return buildFromHermesCommit(version, buildType, artifactsPath);


// [macOS] tag here

Saadnajmi · 2026-04-14T19:11:10Z

packages/react-native/scripts/ios-prebuild/hermes.js

 module.exports = {
  prepareHermesArtifactsAsync,
+  findMatchingHermesVersion, // [macOS] re-exported from macosVersionResolver.js
+  hermesCommitAtMergeBase, // [macOS] re-exported from macosVersionResolver.js


Why do we need the re-exports? should we just import from `macosVesionResolver elsewhere?

Saadnajmi · 2026-04-14T19:12:23Z

packages/react-native/sdks/hermes-engine/utils/build-ios-framework.sh

    elif [[ $1 == "appletvsimulator" ]]; then
      echo "x86_64;arm64"
-    elif [[ $1 == "catalyst" ]]; then
+    elif [[ $1 == "catalyst" || $1 == "macosx" ]]; then


Can we add comments to this file? # [macOS]

Saadnajmi · 2026-04-14T19:13:00Z

packages/react-native/sdks/hermes-engine/utils/build-ios-framework.sh

+    if [[ $1 == "macosx" ]]; then
+      echo "$(get_mac_deployment_target)"


Move to bottom of elsif so we don't need to edit if [[ $1 == "xros" || $1 == "xrsimulator" ]]; then, and then add macOS comments

Saadnajmi · 2026-04-14T19:13:14Z

packages/react-native/sdks/hermes-engine/utils/build-ios-framework.sh

 function build_universal_framework {
    if [ ! -d destroot/Library/Frameworks/universal/hermes.xcframework ]; then
-        create_universal_framework "iphoneos" "iphonesimulator" "catalyst" "xros" "xrsimulator" "appletvos" "appletvsimulator"
+        create_universal_framework "macosx" "iphoneos" "iphonesimulator" "catalyst" "xros" "xrsimulator" "appletvos" "appletvsimulator"


comment # [macOS]

Saadnajmi · 2026-04-14T19:13:33Z

packages/react-native/sdks/hermes-engine/utils/build-ios-framework.sh

 # this is used to preserve backward compatibility
 function create_framework {
    if [ ! -d destroot/Library/Frameworks/universal/hermes.xcframework ]; then
+        build_framework "macosx"


Another # [macOS] tag

Saadnajmi · 2026-04-14T19:14:13Z

packages/react-native/Package.swift

+  excludedPaths: ["Fabric", "Tests", "Resources", "Runtime/RCTJscInstanceFactory.mm", "I18n/strings", "CxxBridge/JSCExecutorFactory.mm", "CoreModules", "RCTUIKit"],
+  dependencies: [.reactNativeDependencies, .reactCxxReact, .reactPerfLogger, .jsi, .reactJsiExecutor, .reactUtils, .reactFeatureFlags, .reactRuntimeScheduler, .yoga, .reactJsInspector, .reactJsiTooling, .rctDeprecation, .reactCoreRCTWebsocket, .reactRCTImage, .reactTurboModuleCore, .reactRCTText, .reactRCTBlob, .reactRCTAnimation, .reactRCTNetwork, .reactFabric, .hermesPrebuilt, .reactRCTUIKit],


// [macOS] commetns to say we added RCTUIKit

Saadnajmi · 2026-04-14T19:15:00Z

packages/react-native/Package.swift

-    "components/view/platform/macos",
+    // "components/view/platform/cxx", // [macOS] excluded on macOS, included on iOS/visionOS (see reactFabricViewPlatformExcludes)
+    // "components/view/platform/macos", // [macOS] excluded on iOS/visionOS, included on macOS (see reactFabricViewPlatformExcludes)


We only excluded macOS, why did we add a commented out line as if we are excluding cxx too?

Saadnajmi · 2026-04-14T19:15:24Z

packages/react-native/Package.swift

+    // "components/view/platform/macos", // [macOS] not needed here — sources don't include components/view
    "components/textinput/platform/android",
    "components/text/platform/android",
-    "components/textinput/platform/macos",


Comment here

- Add missing [macOS] diff tags across Package.swift, hermes.js, and shell build scripts per the diff tag guide - Move macosx case to bottom of get_deployment_target elif chain to minimize upstream diff in build-ios-framework.sh - Remove hermes.js re-exports; import directly from macosVersionResolver - Extract {stdio: 'inherit'} to const in buildFromHermesCommit - Add HERMES_PATH override comment in build-apple-framework.sh - Increase CI artifact retention-days from 1 to 30 - Add commented-out lines for removed upstream excludes in Package.swift Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

Saadnajmi requested a review from a team as a code owner January 17, 2026 03:48

Saadnajmi changed the title ~~feat: Add macOS support to Swift Package Manager build system~~ (claude code generated) feat: Add macOS support to Swift Package Manager build system Jan 17, 2026

Saadnajmi marked this pull request as draft January 17, 2026 03:56

Saadnajmi force-pushed the feature/spm-macos-support branch from a22ab6e to 30d348a Compare March 23, 2026 03:19

Saadnajmi changed the title ~~(claude code generated) feat: Add macOS support to Swift Package Manager build system~~ feat: Add macOS support to Swift Package Manager build system Mar 23, 2026

Saadnajmi mentioned this pull request Mar 23, 2026

fix(spm): fix pre-existing macOS porting bugs #2869

Merged

2 tasks

Saadnajmi force-pushed the feature/spm-macos-support branch 5 times, most recently from fa8de90 to 21908c3 Compare March 23, 2026 15:53

Saadnajmi force-pushed the feature/spm-macos-support branch 5 times, most recently from d1b4bcd to 01e53ee Compare March 26, 2026 18:49

Saadnajmi mentioned this pull request Mar 26, 2026

fix: include macOS slice in universal hermes xcframework facebook/react-native#56235

Closed

This was referenced Apr 3, 2026

fix: include macOS slice in universal hermes xcframework facebook/hermes#1958

Open

fix: include macOS slice in universal Hermes xcframework facebook/hermes#1970

Open

fix: include macOS slice in universal Hermes xcframework facebook/hermes#1971

Open

Saadnajmi force-pushed the feature/spm-macos-support branch from 01e53ee to c1cd032 Compare April 7, 2026 17:49

Saadnajmi changed the title ~~feat: Add macOS support to Swift Package Manager build system~~ feat: include macOS slice in Hermes xcframework Apr 7, 2026

Saadnajmi force-pushed the feature/spm-macos-support branch from c1cd032 to 878f3eb Compare April 7, 2026 17:59

Saadnajmi changed the title ~~feat: include macOS slice in Hermes xcframework~~ feat: Add macOS support to Swift Package Manager build system Apr 7, 2026

Saadnajmi force-pushed the feature/spm-macos-support branch 4 times, most recently from 5fb99f5 to 16e4eb8 Compare April 7, 2026 19:00

Saadnajmi commented Apr 8, 2026

View reviewed changes

Saadnajmi force-pushed the feature/spm-macos-support branch from 49cbeba to 79286e3 Compare April 9, 2026 00:22

tido64 reviewed Apr 9, 2026

View reviewed changes

Saadnajmi and others added 3 commits April 9, 2026 12:06

Saadnajmi force-pushed the feature/spm-macos-support branch 2 times, most recently from 89b00ec to f6714d5 Compare April 9, 2026 20:38

Saadnajmi force-pushed the feature/spm-macos-support branch from f6714d5 to 21f812c Compare April 9, 2026 23:38

github-advanced-security AI found potential problems Apr 9, 2026

View reviewed changes

packages/react-native/scripts/ios-prebuild/reactNativeDependencies.js Dismissed Show dismissed Hide dismissed

Saadnajmi commented Apr 10, 2026

View reviewed changes

Saadnajmi mentioned this pull request Apr 11, 2026

feat(0.81): build React Native macOS with Swift Package Manager #2916

Open

9 tasks

tido64 approved these changes Apr 13, 2026

View reviewed changes

Saadnajmi commented Apr 14, 2026

View reviewed changes

Saadnajmi and others added 2 commits April 14, 2026 13:47

Simplify verbose [macOS] comments

5bb6a84

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

		if [[ $1 == "macosx" ]]; then
		echo "$(get_mac_deployment_target)"

		excludedPaths: ["Fabric", "Tests", "Resources", "Runtime/RCTJscInstanceFactory.mm", "I18n/strings", "CxxBridge/JSCExecutorFactory.mm", "CoreModules", "RCTUIKit"],
		dependencies: [.reactNativeDependencies, .reactCxxReact, .reactPerfLogger, .jsi, .reactJsiExecutor, .reactUtils, .reactFeatureFlags, .reactRuntimeScheduler, .yoga, .reactJsInspector, .reactJsiTooling, .rctDeprecation, .reactCoreRCTWebsocket, .reactRCTImage, .reactTurboModuleCore, .reactRCTText, .reactRCTBlob, .reactRCTAnimation, .reactRCTNetwork, .reactFabric, .hermesPrebuilt, .reactRCTUIKit],

Conversation

Saadnajmi commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Commit 1: SPM macOS support

Commit 2: Include macOS slice in Hermes xcframework

Commit 3: CI jobs

Test plan

Uh oh!

changeset-bot bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tido64 Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tido64 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Saadnajmi Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Saadnajmi commented Jan 17, 2026 •

edited

Loading

changeset-bot bot commented Mar 23, 2026 •

edited

Loading

tido64 Apr 9, 2026 •

edited

Loading

Saadnajmi Apr 14, 2026 •

edited

Loading