Static frameworks: HEADER_SEARCH_PATHS in podspec missing cpp/api, cpp/skia, cpp/jsi, cpp/rnskia, cpp/utils → 'third_party/base64.h' file not found at compile

[Jawish-a]

Summary

When building an iOS app that consumes @shopify/react-native-skia with use_frameworks! :linkage => :static (or Expo's useFrameworks: 'static'), compilation fails on missing headers like:

'third_party/base64.h' file not found

inside node_modules/@shopify/react-native-skia/cpp/api/third_party/base64.cpp.

The header exists at cpp/api/third_party/base64.h, but the HEADER_SEARCH_PATHS setting in react-native-skia.podspec does not include cpp/api. The recursive "$(PODS_TARGET_SRCROOT)/cpp/"/** glob does not propagate when the project uses static frameworks, so individual sub-paths must be listed explicitly.

Affected versions

I've reproduced this on 2.4.18 through 2.6.2, and the current main branch ships the same incomplete line.

"HEADER_SEARCH_PATHS" => '"$(PODS_TARGET_SRCROOT)/cpp/"/** "$(PODS_TARGET_SRCROOT)/cpp" "$(PODS_TARGET_SRCROOT)/cpp/jsi2" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/api" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/api/descriptors" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/async" "$(PODS_TARGET_SRCROOT)/cpp/dawn/include"'

The following directories exist in 2.6.2 and contain headers referenced by sibling .cpp files, but are NOT on the explicit search path:

• cpp/api
• cpp/skia
• cpp/jsi
• cpp/rnskia
• cpp/utils

Environment

• Expo SDK 55 (RN 0.83.6, New Architecture)
• expo-build-properties with useFrameworks: 'static'
• iOS 17/18 SDKs
• Apple Silicon (M-series) Mac
• Reproduced via both expo prebuild && pod install && xcodebuild and EAS Build

Proposed fix

Add the five missing explicit paths to the existing line:

```diff
-"HEADER_SEARCH_PATHS" => '"$(PODS_TARGET_SRCROOT)/cpp/"/** "$(PODS_TARGET_SRCROOT)/cpp" "$(PODS_TARGET_SRCROOT)/cpp/jsi2" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/api" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/api/descriptors" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/async" "$(PODS_TARGET_SRCROOT)/cpp/dawn/include"'
+"HEADER_SEARCH_PATHS" => '"$(PODS_TARGET_SRCROOT)/cpp/"/** "$(PODS_TARGET_SRCROOT)/cpp" "$(PODS_TARGET_SRCROOT)/cpp/api" "$(PODS_TARGET_SRCROOT)/cpp/skia" "$(PODS_TARGET_SRCROOT)/cpp/jsi" "$(PODS_TARGET_SRCROOT)/cpp/jsi2" "$(PODS_TARGET_SRCROOT)/cpp/rnskia" "$(PODS_TARGET_SRCROOT)/cpp/utils" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/api" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/api/descriptors" "$(PODS_TARGET_SRCROOT)/cpp/rnwgpu/async" "$(PODS_TARGET_SRCROOT)/cpp/dawn/include"'
```

These are the same paths I'm currently maintaining via patch-package in my project (regenerated for every Skia version bump). Happy to submit a PR if helpful.

Current workaround

patch-package against the podspec, regenerated per Skia version. Tedious but works.

Related

Reference for users hitting `SkData.h not found` and similar (#652) — same class of static-frameworks header-resolution defect, different missing path.

[mini-777]

Adding a confirmation and one additional trigger that may help maintainers prioritize this.

Reproduced on our app (Expo SDK 55, RN 0.83.6, New Architecture, useFrameworks: 'static') with the exact same
podspec line — same 'third_party/base64.h' file not found error inside cpp/api/third_party/base64.cpp.

A new trigger: EAS Build's precompiled-modules fallback (SDK 55)

This regression hit us this week even though earlier production builds with the same Skia 2.6.2 + useFrameworks: 'static' had been passing for months. The difference turned out to be EAS-side, not ours:

• Per the Expo Prebuilt Modules docs,
  EXPO_USE_PRECOMPILED_MODULES is default-on on EAS Build for SDK 55.

• For our Skia version, the precompiled xcframework wasn't available in the EAS cache, so the build fell back to source:

  [Expo-precompiled] react-native-skia: remote debug artifact unavailable (HTTP 404); building from source
  [Expo-precompiled] URL: .../react-native-skia/output/2.6.2/0.83.1/0.14.0/debug/xcframeworks/RNSkia.tar.gz

• EAS then source-builds Skia — and this is exactly when the podspec's incomplete HEADER_SEARCH_PATHS surfaces and the
  compile fails.

So projects can pass for a while (precompiled artifact works), then suddenly break on a routine JS-only commit (404
fallback kicks in). The trigger looks unrelated to Skia, which makes the root cause hard to find. Diffing build logs
between the last green build and the failing one is what pointed us here — EAS_USE_PRECOMPILED_MODULES=1 was present in
the failing build's env and absent in the passing one.

Workaround that doesn't require patch-package

For folks who want to avoid patch-package, Expo Autolinking's buildFromSource option works cleanly:

// package.json
{
"expo": {
  "autolinking": {
    "ios": {
      "buildFromSource": ["@shopify/react-native-skia"]
    }
  }
}
}

This forces Skia to source-build directly (so the precompiled→fallback path isn't taken), while keeping precompiled
benefits for other modules (Reanimated, SVG, Screens, Worklets, etc.). One-line config change, no native patching, and
easy to remove once a Skia release ships @op's proposed podspec fix.

Reference: Expo docs — Disabling specific modules via Expo Autolinking.

Re: the proposed fix

@op's diff (adding cpp/api, cpp/skia, cpp/jsi, cpp/rnskia, cpp/utils to HEADER_SEARCH_PATHS) matches exactly what we
observed in build logs — the recursive "cpp/"/** glob silently drops these sibling dirs in static-frameworks mode. A small
podspec PR would resolve this for everyone hitting it. Happy to help verify or test a fix on our setup.

Thanks!

[jieey1140]

+1

[wcandillon]

I have a fix for it at #3853
Thank You for your patience with this 🙏

[github-actions]

🎉 This issue has been resolved in version 2.6.3 🎉

The release is available on:

• v2.6.3
• GitHub release

Your semantic-release bot 📦🚀