Proposal: improve modulesProvider() failure mode when CFBundleName cannot be used as a Swift module name (SDK 56, iOS 26)

[marcospgp]

Proposal: improve modulesProvider() failure mode when CFBundleName cannot be used as a Swift module name (SDK 56, iOS 26)

Background

AppContext.modulesProvider() in expo-modules-core looks up the autogenerated ExpoModulesProvider class via NSClassFromString in a four-step fallback chain, and returns an empty ModulesProvider() if every step fails. The empty stub means the entire native-module registry is silently empty for the lifetime of the app. Every requireNativeModule("X") throws Cannot find native module 'X'. The app dies inside expo-router/entry before any user code runs, with no log or warning from expo-modules-core itself pointing at the actual cause.

The lookup chain (from expo-modules-core/ios/Core/AppContext.swift):

public static func modulesProvider(withName providerName: String = "ExpoModulesProvider") -> ModulesProvider {
  // [0] When ExpoModulesCore is built as separated framework/module
  if let bundleName = Bundle.main.infoDictionary?["CFBundleName"],
     let providerClass = NSClassFromString("\(bundleName).\(providerName)") as? ModulesProvider.Type {
    return providerClass.init()
  }
  // [1] Fallback to `ExpoModulesProvider` class from the current module.
  if let providerClass = NSClassFromString(providerName) as? ModulesProvider.Type {
    return providerClass.init()
  }
  // [2] Fallback to search for `ExpoModulesProvider` in frameworks (brownfield use case)
  for bundle in Bundle.allFrameworks {
    guard let bundleName = bundle.infoDictionary?["CFBundleName"] as? String else { continue }
    if let providerClass = NSClassFromString("\(bundleName).\(providerName)") as? ModulesProvider.Type {
      return providerClass.init()
    }
  }
  // [3] Fallback to an empty `ModulesProvider`
  return ModulesProvider()
}

How we tripped on this

Our app.config.ts overrode infoPlist.CFBundleName to the human-readable display name ("Ink & Quill"). The Xcode PRODUCT_NAME is InkQuill (valid Swift module identifier), so the Swift module name is InkQuill. At runtime:

Step	Lookup string	Result	Why
[0]	"Ink & Quill.ExpoModulesProvider"	nil	Swift module is InkQuill, not Ink & Quill. Spaces and & are invalid in Swift module identifiers.
[1]	"ExpoModulesProvider"	nil	See forensics.
[2]	walks Bundle.allFrameworks	nil	The app is the main bundle, not a framework.
[3]	empty ModulesProvider()	returned	Registry empty for the lifetime of the app.

We spent roughly four hours bisecting React Native versions, the New Architecture flag, Bun's content-addressed package store, and expo-modules-autolinking output before reading AppContext.swift source. The actual fix is one line in app.config.ts: stop overriding CFBundleName, let it default to $(PRODUCT_NAME). The user-facing display name lives in CFBundleDisplayName, which Expo's prebuild derives from the top-level name field automatically.

Forensics on step [1]

The autogenerated Pods/Target Support Files/Pods-MyApp/ExpoModulesProvider.swift declares:

@objc(ExpoModulesProvider)
internal class ExpoModulesProvider: ModulesProvider { ... }

The intent of @objc(ExpoModulesProvider) is to register the class with the Objective-C runtime under the bare name ExpoModulesProvider so step [1] succeeds regardless of CFBundleName. On our setup it does not.

nm on the built .app binary returns only Swift-mangled symbols:

_$s8InkQuill19ExpoModulesProviderC16getModuleClassesSay...
_$s8InkQuill19ExpoModulesProviderC25getAppDelegateSubscribers...
_$s8InkQuill19ExpoModulesProviderC26getAppCodeSignEntitlements...
_$s8InkQuill19ExpoModulesProviderCACycfC
...

There is no _OBJC_CLASS_$_ExpoModulesProvider entry. NSClassFromString("ExpoModulesProvider") returns nil because the bare-name ObjC class symbol is missing. The same is true for the intermediate .o file in DerivedData/.../Objects-normal/arm64/ExpoModulesProvider.o.

This looks like a Swift 6 / Xcode 26 interaction with @objc(...) on internal classes, but I have not isolated it to a minimal Swift project. Either Swift 6 requires public for @objc(...) to emit the ObjC class symbol, or the autogenerated file needs a different declaration shape. Step [1] is supposed to be the safety net; right now it is not.

Environment

• Expo SDK: 56.0.6 (also reproduces on 56.0.4)
• React Native: 0.85.3
• JS engine: Hermes
• iOS: 26.2 (simulator and physical iPhone)
• Xcode: 26.x
• Architecture: New Architecture on (SDK 56 default, no opt-out path available)
• Package manager: Bun in a hoisted monorepo layout
• Build type: Debug

Proposals

Three independent changes, any subset of which prevents this debugging session from happening again.

1. Validate CFBundleName at prebuild time

The misconfiguration is detectable statically. expo prebuild could reject infoPlist.CFBundleName values containing characters invalid in a Swift module identifier, and point at CFBundleDisplayName for the user-facing name. A clear error at prebuild time instead of an opaque runtime crash.

2. Make step [3] fail loud instead of silent

The empty-stub fallback in modulesProvider() is the failure mode that costs hours. Replacing it with a thrown error that includes the lookup chain converts ten meaningless JS errors into one actionable native error:

Fatal: ExpoModulesProvider class not found. Tried:
  - "\(CFBundleName).ExpoModulesProvider"  → nil
  - "ExpoModulesProvider"                  → nil
  - "<frameworkName>.ExpoModulesProvider"  → nil for all loaded frameworks
Verify that CFBundleName matches the Xcode PRODUCT_NAME and contains no characters invalid in a Swift module identifier.
Note: CFBundleDisplayName is the user-facing name; CFBundleName must be a valid Swift module identifier.

This is the change that would have unblocked us in seconds. The silent stub also makes step [3] indistinguishable from "this is a brownfield project with no Expo modules at all", which is its only legitimate use case. Distinguishing the two would be valuable on its own.

3. Fix the @objc(ExpoModulesProvider) registration on Swift 6 / Xcode 26

Step [1] is the architectural safety net for any CFBundleName mismatch. If the bare-name ObjC class symbol were emitted, the lookup chain would survive any reasonable misconfiguration. Two avenues to investigate:

• Change the autogenerated Pods-{App}/ExpoModulesProvider.swift template to use public class instead of internal class. Test whether that restores the _OBJC_CLASS_$_ExpoModulesProvider symbol on Swift 6 / Xcode 26.
• Move away from NSClassFromString of a string derived from CFBundleName. The autogenerated provider could register itself in a known runtime registry at load time (+load or a static initializer), and modulesProvider() could read from that registry. This is harder but removes the dependency on the runtime-derived class name entirely.

Why a proposal and not a bug

This is two separate issues: a user-side misconfiguration that should have been caught earlier, and a registration failure mode that may or may not be Expo-side. I have not isolated either to a minimal repro and I do not have time to do so right now. The lookup chain itself is the lever Expo controls, and any of the three proposals above neutralizes the trap regardless of which root cause is closer to Expo's domain. Happy to test patches against our setup if it helps.