[0.84.0] [iOS] Mac Catalyst build failed with bundle format is ambiguous (could be app or framework)

Issues

Upgrading to 0.84 broke build for Mac Catalyst, with the error "bundle format is ambiguous (could be app or framework)"

There are several issues:

1. Hermes 250829098.0.7 (shipped with 0.84) has the wrong symlinks in the framework for Mac Catalyst. (This has been fixed in 250829098.0.8; see https://github.com/facebook/hermes/issues/1883)

2. React Native pre-built dependencies also have the wrong symlinks as well as invalid structures.

   ls -al ReactNativeDependencies.xcframework/ios-arm64_x86_64-maccatalyst/ReactNativeDependencies.framework

   -rw-r--r--  1 rying  staff  6963960 Feb 11 06:48 ReactNativeDependencies
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 ReactNativeDependencies_boost.bundle
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 ReactNativeDependencies_folly.bundle
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 ReactNativeDependencies_glog.bundle
   drwxr-xr-x  3 rying  staff       96 Feb 11 06:48 Resources
   drwxr-xr-x  4 rying  staff      128 Feb 11 06:48 Versions
   

   ls -al React.xcframework/ios-arm64_x86_64-maccatalyst/React.framework

   drwxr-xr-x  63 rying  staff       2016 Feb 11 07:15 Headers
   drwxr-xr-x   3 rying  staff         96 Feb 11 07:15 Modules
   -rw-r--r--   1 rying  staff  114967784 Feb 11 07:14 React
   drwxr-xr-x   3 rying  staff         96 Feb 11 07:14 Resources
   drwxr-xr-x   4 rying  staff        128 Feb 11 07:14 Versions
   

Expectations

1. The correct symlinks shoud look like this

   lrwxr-xr-x  1 rying  staff   40 Feb 12 21:37 ReactNativeDependencies -> Versions/Current/ReactNativeDependencies
   lrwxr-xr-x  1 rying  staff   26 Feb 12 21:37 Resources -> Versions/Current/Resources
   drwxr-xr-x@ 4 rying  staff  128 Feb 12 21:37 Versions
   

2. ReactNativeDependencies_boost.bundle etc. cannot be in the directory ReactNativeDependencies.framework. These bundles need to be moved to under Versions/Current/Resources instead.

Workarounds

1. Download the newer version of Hermes 250829098.0.8 from https://repo1.maven.org/maven2/com/facebook/hermes/hermes-ios and use it for pod install: HERMES_ENGINE_TARBALL_PATH=/Users/rying/Downloads/hermes-ios-250829098.0.8-hermes-ios-debug.tar.gz pod install

2. Here is a script that fixes the pre-built dependencies' framework structures:

   pushd ios/Pods/hermes-engine/destroot/Library/Frameworks/universal/hermesvm.xcframework/ios-arm64_x86_64-maccatalyst/hermesvm.framework
   rm -r hermesvm Resources        
   ln -s Versions/Current/Resources Resources
   ln -s Versions/Current/hermesvm hermesvm
   pushd Versions && rm -r Current && ln -s 1 Current && popd
   popd
   
   pushd ios/Pods/React-Core-prebuilt/React.xcframework/ios-arm64_x86_64-maccatalyst/React.framework
   rm -r React Resources
   ln -s Versions/Current/Resources Resources
   ln -s Versions/Current/React React
   pushd Versions && rm -r Current && ln -s A Current && popd
   popd
   
   pushd ios/Pods/ReactNativeDependencies/framework/packages/react-native/ReactNativeDependencies.xcframework/ios-arm64_x86_64-maccatalyst/ReactNativeDependencies.framework
   rm -r ReactNativeDependencies Resources
   ln -s Versions/Current/Resources Resources
   ln -s Versions/Current/ReactNativeDependencies ReactNativeDependencies
   pushd Versions && rm -r Current && ln -s A Current && popd
   mv ReactNativeDependencies_*.bundle Resources
   popd
   

Steps to reproduce

1. Create a new RN project with CLI
2. Install node modules, pods, etc.
3. Open Xcode and enable Mac Catalyst support by adding it as a destination
4. Run the project with the Mac Catalyst as the target
5. Observe build errors

React Native Version

0.84.0

Affected Platforms

Build - MacOS

Output of npx @react-native-community/cli info

System:
  OS: macOS 26.3
  CPU: (10) arm64 Apple M1 Pro
  Memory: 1.13 GB / 16.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 25.6.1
    path: /Users/rying/.nvm/versions/node/v25.6.1/bin/node
  Yarn: Not Found
  npm:
    version: 11.9.0
    path: /Users/rying/.nvm/versions/node/v25.6.1/bin/npm
  Watchman: Not Found
Managers:
  CocoaPods:
    version: 1.16.2
    path: /opt/homebrew/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 25.2
      - iOS 26.2
      - macOS 26.2
      - tvOS 26.2
      - visionOS 26.2
      - watchOS 26.2
  Android SDK: Not Found
IDEs:
  Android Studio: 2025.2 AI-252.28238.7.2523.14688667
  Xcode:
    version: 26.3/17C519
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.18
    path: /opt/homebrew/Cellar/openjdk@17/17.0.18/libexec/openjdk.jdk/Contents/Home/bin/javac
  Ruby:
    version: 2.6.10
    path: /usr/bin/ruby
npmPackages:
  "@react-native-community/cli":
    installed: 20.1.1
    wanted: 20.1.1
  react:
    installed: 19.2.3
    wanted: 19.2.3
  react-native:
    installed: 0.84.0
    wanted: 0.84.0
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true
  newArchEnabled: true

Stacktrace or Logs

N/A

MANDATORY Reproducer

https://github.com/robertying/rn84-mac-catalyst-build-error

Screenshots and Videos

No response

先执行必需的 reproducer 和列出的 Catalyst 构建步骤，然后检查 ios/Pods 下生成的 ReactNativeDependencies.xcframework、React.xcframework 和 hermesvm.framework 路径。将它们的 Catalyst framework 符号链接和 bundle 位置与 issue 中预期的结构进行比较。当修正后的预构建 framework 安装完成，并且 React Native 项目能够针对 Mac Catalyst 目标进行构建而不出现歧义的 bundle-format 错误时，即表示完成。