Custom Headers not working with v11 Alpha

[victorcg03]

Context

I’m migrating an app to @maplibre/maplibre-react-native v11 alpha to benefit from better New Architecture support (Fabric + Hermes).
With v10.2.0 I can inject custom HTTP headers for vector tile/style requests using MLRNCustomHeaders without any issues.
On v11 alpha the same approach fails at build time on iOS.

Environment (high level):

• React Native via Expo dev client (prebuild + expo run:ios)
• New Architecture enabled + Hermes (newArchEnabled: true, jsEngine: "hermes")
• iOS deployment target 15.1
• Xcode 15.x
• @maplibre/maplibre-react-native: v10.2.0 (works) → v11.0.0-alpha.x (fails)

---

What works on v10.2.0

AppDelegate.swift

// Expo RN factory setup above …

#if os(iOS) || os(tvOS)
  window = UIWindow(frame: UIScreen.main.bounds)
  MLRNCustomHeaders().initHeaders()
  MLRNCustomHeaders().addHeader("sECrEt", forHeaderName: "Authorization")

  factory.startReactNative(
    withModuleName: "main",
    in: window,
    launchOptions: launchOptions
  )
#endif

Bridging header

// GlobalIPCert-Bridging-Header.h
#import "MLRNCustomHeaders.h"

JS (later, when I have the token)

import { addCustomHeader } from '@maplibre/maplibre-react-native';

addCustomHeader('Authorization', `Bearer ${token}`);

✅ This reliably sends headers to my tile/style backend (verified in server logs).

---

What fails on v11 alpha

If I keep the same code and just bump to v11 alpha:

• Using the bridging header with either:

#import "MLRNCustomHeaders.h"

or

#import <MapLibreReactNative/MLRNCustomHeaders.h>

I get:

'MLRNCustomHeaders.h' file not found
'MapLibreReactNative/MLRNCustomHeaders.h' file not found

• If I don’t use a bridging header and try to go pure Swift:

#if canImport(MapLibreReactNative)
import MapLibreReactNative
#endif

// ...
MLRNCustomHeaders().initHeaders()   // ❌

I get:

cannot find 'MLRNCustomHeaders' in scope

So it looks like MLRNCustomHeaders is either not exported publicly in v11 alpha, or the API/name changed.

---

Repro steps

1. Expo prebuild project, New Architecture enabled + Hermes.
2. Install @maplibre/[email protected].
3. Add the MLRNCustomHeaders calls in AppDelegate.swift (as shown above).
4. Build with expo run:ios --device (or via Xcode).
5. Build fails with the errors quoted above.

---

What I tried

• Bridging header include with both local and module-style imports → header not found.
• Pure Swift + import MapLibreReactNative and #if canImport(...) → symbol not found.
• Full Pods clean / pod install / clean DerivedData.
• Verified the same code works on v10.2.0 in the same project.

---

Questions

1. What is the correct way to initialize and use custom headers on iOS with v11 alpha?
2. Is MLRNCustomHeaders still the intended API? Has it been renamed/moved?
3. Should we avoid bridging headers and import a Swift symbol instead?
4. Is there a recommended native initialization step for headers in v11 alpha?
   In v10, calling initHeaders() in AppDelegate ensures some early requests (style/tiles) also include headers before JS calls addCustomHeader. What’s the equivalent in v11 alpha?
5. If the public header/class was intentionally removed in alpha, what’s the new supported approach to set default headers for all MapLibre network requests from RN (before the first <MapView/> mounts)?

Any guidance or pointer to the right header/module/API in v11 alpha would be super helpful.
Thanks a lot!

---

Extra (server logs showing missing headers without native init)

When relying only on JS addCustomHeader without native init, I see early requests hitting my server without Authorization (style/tiles load before JS runs). Initializing headers in AppDelegate solved that on v10.

---

Environment details (exact versions & config)

package.json

{ 
  "dependencies": {
    "@maplibre/maplibre-react-native": "^10.2.0",
    "expo": "53.0.20",
    "react": "19.0.0",
    "react-native": "0.79.5",
    "expo-dev-client": "~5.2.4"
  },

or

{ 
  "dependencies": {
    "@maplibre/maplibre-react-native": "^11.0.0-alpha.5",
    "expo": "53.0.20",
    "react": "19.0.0",
    "react-native": "0.79.5",
    "expo-dev-client": "~5.2.4"
  },

app.config.ts

import { ConfigContext, ExpoConfig } from "expo/config";
export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  newArchEnabled: true,
  jsEngine: "hermes",
  plugins: [
    "@maplibre/maplibre-react-native",
  ],
});

[KiwiKilian]

This is a bug, see #1050.