XCFramework

Le format d’Apple pour livrer un framework binaire multi-plateformes (device, simulateur, macOS) en un bundle ; React Native y livre son cœur précompilé.

Mis à jour le 26 octobre 2026

Définition

Un XCFramework est le format de bundle d’Apple pour distribuer un framework ou une librairie binaire déjà compilée pour plusieurs plateformes et architectures : iOS sur appareil (arm64), simulateur iOS (arm64 et x86_64), macOS, tvOS. Chaque combinaison occupe sa propre tranche dans le bundle, et Xcode choisit la bonne à la compilation. Il remplace les « fat frameworks » assemblés avec lipo, qui ne peuvent pas contenir à la fois une tranche appareil et une tranche simulateur quand les deux sont en arm64, ce qui est le cas depuis les Mac Apple Silicon. On le crée avec xcodebuild -create-xcframework à partir des frameworks ou librairies statiques de chaque plateforme. Pour React Native, c’est le format des binaires précompilés : depuis la 0.84, le cœur (ReactNativeCore) et ses dépendances sont téléchargés en .xcframework au pod install au lieu d’être compilés depuis les sources. Vous le rencontrez dans un SDK tiers livré en binaire, dans le dossier Pods d’un projet récent, ou dans une erreur de linkage.

Dans une vraie app

Dans un projet React Native à jour, ls ios/Pods montre des .xcframework pour React Native, ses dépendances tierces (boost, folly, glog, fmt) et Hermes ; RCT_USE_PREBUILT_RNCORE=0 bundle exec pod install force le retour aux sources, utile pour déboguer dans le cœur ou appliquer un patch. Avec SwiftPM, ce sont les mêmes XCFrameworks qui sont consommés, plus deux bundles d’en-têtes (ReactNativeHeaders, ReactNativeDependenciesHeaders) introduits en 0.87.

Les erreurs typiques se lisent au link : « building for iOS Simulator, but linking in object file built for iOS » signale un binaire sans tranche simulateur arm64, fréquent avec un SDK tiers ancien ; la solution est une version à jour du SDK, pas l’exclusion d’architecture EXCLUDED_ARCHS=arm64 qui condamne au simulateur Rosetta. Un XCFramework signé par son éditeur peut aussi échouer à la vérification de signature si Xcode est configuré pour l’exiger.

Pour une librairie maison distribuée en binaire, la question à poser est la compatibilité des versions : un XCFramework Swift compilé sans « library evolution » (BUILD_LIBRARY_FOR_DISTRIBUTION) ne fonctionne qu’avec la version exacte du compilateur qui l’a produit, et un XCFramework compilé contre une version de React Native ne se linke pas forcément avec la suivante. C’est la raison pour laquelle les binaires du cœur sont publiés par version exacte et téléchargés depuis le miroir Maven de React Native, avec Maven Central en secours.

Sources

Les 35 termes du glossaire

Dans une vraie app

Termes liés

Sources

Un de ces sujets bloque votre app ?