Shipping OpenCV in an Expo Module Without the Setup Tax

The first time I put OpenCV into a React Native app — a 360° photosphere feature for a real-estate product back in 2024 — the actual computer vision was the easy part. The hard part was getting OpenCV to exist in the build at all.

On iOS that meant downloading opencv2.framework, vendoring it into the repo, and then fighting Xcode because the framework didn't ship an arm64 simulator slice, so every build on an Apple Silicon Mac needed an EXCLUDED_ARCHS hack to even compile. On Android it meant downloading the OpenCV-android-sdk, wiring jniLibs.srcDirs, and writing CMake + JNI glue to reach the C++ from Java. Two completely different setups, both of them the kind of thing you get working once and then never want to touch again.

I just rebuilt that work as an open-source Expo module — expo-panoramic-stitcher — and the dependency story is now one line per platform. This is what changed.

Android: OpenCV is just a Maven dependency now

The single biggest improvement is that OpenCV publishes to Maven Central with a real Java/Kotlin API and the native libraries bundled inside the package:

implementation 'org.opencv:opencv:4.13.0'

That's the whole Android setup. No OpenCV-android-sdk folder in the repo, no jniLibs, no CMake, no NDK, no JNI bridge. The module is plain Kotlin calling org.opencv.stitching.Stitcher directly:

val stitcher = Stitcher.create(if (warpMode == "plane") Stitcher.SCANS else Stitcher.PANORAMA)
stitcher.setPanoConfidenceThresh(matchConf.toDouble())
 
val pano = Mat()
val status = stitcher.stitch(images, pano)
if (status != Stitcher.OK) {
  throw StitchException("OpenCV stitch failed (status $status). Ensure 30-40% overlap.")
}

You load OpenCV once with OpenCVLoader.initLocal() and from then on it's ordinary Kotlin. The pain is genuinely gone.

iOS: a prebuilt XCFramework over Swift Package Manager

iOS is where the old setup hurt most, and where the fix is most satisfying. Instead of vendoring a framework, the podspec declares an SPM dependency on a prebuilt OpenCV XCFramework:

s.spm_dependency(
  url: 'https://github.com/yeatse/opencv-spm.git',
  requirement: { kind: 'upToNextMajorVersion', minimumVersion: '4.13.0' },
  products: ['OpenCV']
)

The XCFramework ships both device and arm64-simulator slices. That one detail retires the entire EXCLUDED_ARCHS simulator dance — the simulator just builds, because the architecture it needs is actually in the binary. pod install resolves and caches it once. The only requirement is CocoaPods ≥ 1.16, which is when spm_dependency landed.

You still need one C++ shim — and that's fine

Here's the part people hope a new module system will erase, and it won't: OpenCV is a C++ library with no Swift API. Something has to cross from Swift into C++. So iOS keeps exactly one thin Objective-C++ file — about 140 lines — that wraps cv::Stitcher, reads and writes images with cv::imread/cv::imwrite, and hands back a plain dictionary:

cv::Stitcher::Mode mode = [self modeForWarp:warpMode];
cv::Ptr<cv::Stitcher> stitcher = cv::Stitcher::create(mode);
cv::Mat pano;
cv::Stitcher::Status status = stitcher->stitch(images, pano);

Swift reaches it through a normal Objective-C header — no manual bridging header, just SWIFT_OBJC_INTEROP_MODE = objcxx in the pod config — and the Expo module on top is plain Swift. Android needs no shim, because Maven already gave us a Kotlin API.

I want to be clear about this because it's a common misconception: switching to Nitro Modules wouldn't delete this shim. Nitro changes how JS talks to native; it doesn't change that OpenCV is C++. The Obj-C++ layer isn't a bridge tax you can remove with a better module system — it's the actual Swift↔C++ seam.

The design lesson: make the platforms symmetric

The setup was half the battle. The other half was not ending up with two implementations that drift apart — which is exactly what happened in my 2024 version, where iOS returned base64 and Android returned raw RGBA bytes, and the JS had to branch on Platform.OS.

The fix this time was a rule: native code only ever operates on image file paths. The core function takes paths in and writes a JPEG out. Everything else is built on top of it in Swift/Kotlin — the base64 variant just decodes inputs to temp files, runs the same path-based stitch, and re-encodes the result:

export function stitchBase64(images: string[], options?: StitchOptions) {
  if (!images || images.length < 2) {
    throw new Error("At least 2 images are required for stitching");
  }
  return ExpoPanoramicStitcher.stitchBase64(images, { ...DEFAULTS, ...options });
}

Because both platforms share that contract, they return the identical StitchBase64Result shape and the JS layer never has to know which OS it's on. The C++/OpenCV surface stays tiny, the two platforms stay honest, and the incremental "add one frame at a time" API falls out of the same core for free.

What it actually costs you now

For comparison, the old way vs this module:

• Android OpenCV — was: download the SDK, wire jniLibs, write CMake + JNI. Now: one implementation line, pure Kotlin.
• iOS OpenCV — was: vendor opencv2.framework, fight simulator arches. Now: one spm_dependency, no arch hack.
• iOS bridge — was: Swift → ObjC++ → C++, two layers. Now: Swift → one ~140-line shim.
• Result payload — was: asymmetric per platform. Now: identical on both.

None of this makes the computer vision easier — stitching still needs ~30–40% overlap between shots or OpenCV refuses, and that's a real constraint you design the capture UX around. But the plumbing that used to eat a day and rot in the repo is now a few lines I'd happily set up again. That's the difference the Expo Modules API, Maven's OpenCV package, and SPM XCFrameworks have made between 2024 and now.

The module is open source under MIT — published to npm and GitHub Packages as @notchip/expo-panoramic-stitcher, installable with npx expo install @notchip/expo-panoramic-stitcher. It's still in testing across device classes, so bug reports from real shoots are exactly what I'm after.