Files
skills/public/mobile-react-native-native-modules.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

742 lines
32 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>mobile-react-native-native-modules</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/mobile-react-native-native-modules">
<link rel="alternate" type="text/markdown" href="/mobile-react-native-native-modules.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/mobile-react-native-native-modules.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>mobile-react-native-native-modules</h1><p class="lede">Accessing iOS-specific APIs not available in React Native</p><h1>React Native Native Modules</h1>
<p><strong>Scope</strong>: Native modules, bridging Swift/Objective-C, iOS APIs, TurboModules, native UI components <strong>Lines</strong>: ~350 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Accessing iOS-specific APIs not available in React Native</li><li>Implementing performance-critical native functionality</li><li>Integrating third-party iOS SDKs</li><li>Creating custom native UI components</li><li>Bridging existing Swift/Objective-C code to React Native</li><li>Using iOS hardware features (Camera, Bluetooth, etc.)</li><li>Implementing native background tasks or services</li></ul>
<h2>Core Concepts</h2>
<h3>Native Module Architecture</h3>
<p><strong>Bridge Pattern</strong>:</p>
<ul><li>JavaScript thread runs React Native code</li><li>Native thread runs iOS code</li><li>Bridge serializes data between threads (JSON-like)</li><li>Asynchronous by default (callbacks/promises)</li></ul>
<p><strong>TurboModules</strong> (New Architecture):</p>
<ul><li>Direct JavaScript to native communication (no bridge)</li><li>Type-safe with Codegen</li><li>Synchronous methods possible</li><li>Better performance (lazy loading)</li></ul>
<p><strong>Communication Flow</strong>:</p>
<pre><code>JavaScript → Bridge → Native Module → iOS API
iOS API → Native Module → Bridge → JavaScript</code></pre>
<h3>Swift Bridging</h3>
<p><strong>Bridging Header</strong> (Objective-C interop):</p>
<ul><li>Required for Swift modules in RN &lt; 0.74</li><li>Exposes Swift to Objective-C runtime</li><li>Auto-generated by Xcode</li><li>Manual updates for custom types</li></ul>
<p><strong>@objc Attribute</strong>:</p>
<ul><li>Makes Swift code visible to Objective-C</li><li>Required for RCT macros</li><li>Adds some runtime overhead</li><li>Necessary for React Native bridge</li></ul>
<h3>Event Emitters</h3>
<p><strong>Push vs Pull</strong>:</p>
<ul><li>Callbacks: One-time data return</li><li>Promises: Single async result</li><li>Events: Continuous stream of data</li></ul>
<p><strong>Use Cases</strong>:</p>
<ul><li>Sensor data (accelerometer, GPS)</li><li>Notifications (local, push)</li><li>Network state changes</li><li>Background task updates</li></ul>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Basic Swift Native Module</h3>
<pre><code class="lang-swift">// ios/MyModule.swift
import Foundation
import React
@objc(MyModule)
class MyModule: NSObject {
// MARK: - React Native Export
@objc
static func requiresMainQueueSetup() -&gt; Bool {
return false // Run on background thread
}
@objc
func greet(_ name: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {
let greeting = &quot;Hello, \(name)!&quot;
resolver(greeting)
}
@objc
func calculateSum(_ a: NSNumber, b: NSNumber, callback: @escaping RCTResponseSenderBlock) {
let sum = a.doubleValue + b.doubleValue
callback([NSNull(), sum]) // [error, result] pattern
}
@objc
func getDeviceInfo() -&gt; NSDictionary {
return [
&quot;model&quot;: UIDevice.current.model,
&quot;systemVersion&quot;: UIDevice.current.systemVersion,
&quot;name&quot;: UIDevice.current.name
]
}
}</code></pre>
<pre><code class="lang-objective-c">// ios/MyModule.m (Bridging file)
#import &lt;React/RCTBridgeModule.h&gt;
@interface RCT_EXTERN_MODULE(MyModule, NSObject)
RCT_EXTERN_METHOD(greet:(NSString *)name
resolver:(RCTPromiseResolveBlock)resolve
rejecter:(RCTPromiseRejectBlock)reject)
RCT_EXTERN_METHOD(calculateSum:(nonnull NSNumber *)a
b:(nonnull NSNumber *)b
callback:(RCTResponseSenderBlock)callback)
RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(getDeviceInfo)
@end</code></pre>
<pre><code class="lang-typescript">// src/modules/MyModule.ts
import { NativeModules } from &#x27;react-native&#x27;;
interface MyModuleInterface {
greet(name: string): Promise&lt;string&gt;;
calculateSum(a: number, b: number, callback: (error: any, result: number) =&gt; void): void;
getDeviceInfo(): { model: string; systemVersion: string; name: string };
}
const { MyModule } = NativeModules;
export default MyModule as MyModuleInterface;</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Type-safe TypeScript interface</li><li>Async methods with promises</li><li>Synchronous methods for simple data</li><li>Callback pattern for legacy code</li></ul>
<h3>Pattern 2: Event Emitter Native Module</h3>
<pre><code class="lang-swift">// ios/SensorModule.swift
import Foundation
import CoreMotion
import React
@objc(SensorModule)
class SensorModule: RCTEventEmitter {
private var motionManager: CMMotionManager?
private var isObserving = false
override init() {
super.init()
motionManager = CMMotionManager()
}
// MARK: - React Native Export
override static func requiresMainQueueSetup() -&gt; Bool {
return false
}
override func supportedEvents() -&gt; [String]! {
return [&quot;onAccelerometerData&quot;, &quot;onDeviceMotion&quot;]
}
@objc
func startAccelerometer() {
guard let manager = motionManager, !isObserving else { return }
isObserving = true
manager.accelerometerUpdateInterval = 0.1
manager.startAccelerometerUpdates(to: .main) { [weak self] (data, error) in
guard let data = data, error == nil else { return }
self?.sendEvent(withName: &quot;onAccelerometerData&quot;, body: [
&quot;x&quot;: data.acceleration.x,
&quot;y&quot;: data.acceleration.y,
&quot;z&quot;: data.acceleration.z,
&quot;timestamp&quot;: Date().timeIntervalSince1970
])
}
}
@objc
func stopAccelerometer() {
motionManager?.stopAccelerometerUpdates()
isObserving = false
}
override func stopObserving() {
stopAccelerometer()
}
}</code></pre>
<pre><code class="lang-objective-c">// ios/SensorModule.m
#import &lt;React/RCTBridgeModule.h&gt;
#import &lt;React/RCTEventEmitter.h&gt;
@interface RCT_EXTERN_MODULE(SensorModule, RCTEventEmitter)
RCT_EXTERN_METHOD(startAccelerometer)
RCT_EXTERN_METHOD(stopAccelerometer)
@end</code></pre>
<pre><code class="lang-typescript">// src/modules/SensorModule.ts
import { NativeEventEmitter, NativeModules } from &#x27;react-native&#x27;;
const { SensorModule } = NativeModules;
const sensorEmitter = new NativeEventEmitter(SensorModule);
export interface AccelerometerData {
x: number;
y: number;
z: number;
timestamp: number;
}
export const startAccelerometer = () =&gt; {
SensorModule.startAccelerometer();
};
export const stopAccelerometer = () =&gt; {
SensorModule.stopAccelerometer();
};
export const subscribeToAccelerometer = (
callback: (data: AccelerometerData) =&gt; void
) =&gt; {
const subscription = sensorEmitter.addListener(&#x27;onAccelerometerData&#x27;, callback);
return () =&gt; subscription.remove();
};</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Continuous data streams (sensors, location)</li><li>Push notifications or system events</li><li>Real-time updates from native code</li><li>Background task status updates</li></ul>
<h3>Pattern 3: Native UI Component (Swift)</h3>
<pre><code class="lang-swift">// ios/CircularProgressView.swift
import UIKit
class CircularProgressView: UIView {
private var progressLayer = CAShapeLayer()
private var trackLayer = CAShapeLayer()
@objc var progress: CGFloat = 0 {
didSet {
updateProgress()
}
}
@objc var progressColor: UIColor = .systemBlue {
didSet {
progressLayer.strokeColor = progressColor.cgColor
}
}
@objc var trackColor: UIColor = .systemGray5 {
didSet {
trackLayer.strokeColor = trackColor.cgColor
}
}
override func layoutSubviews() {
super.layoutSubviews()
setupLayers()
}
private func setupLayers() {
let center = CGPoint(x: bounds.midX, y: bounds.midY)
let radius = min(bounds.width, bounds.height) / 2 - 10
let circularPath = UIBezierPath(
arcCenter: center,
radius: radius,
startAngle: -.pi / 2,
endAngle: 3 * .pi / 2,
clockwise: true
)
// Track layer
trackLayer.path = circularPath.cgPath
trackLayer.fillColor = UIColor.clear.cgColor
trackLayer.strokeColor = trackColor.cgColor
trackLayer.lineWidth = 10
trackLayer.lineCap = .round
// Progress layer
progressLayer.path = circularPath.cgPath
progressLayer.fillColor = UIColor.clear.cgColor
progressLayer.strokeColor = progressColor.cgColor
progressLayer.lineWidth = 10
progressLayer.lineCap = .round
progressLayer.strokeEnd = 0
layer.addSublayer(trackLayer)
layer.addSublayer(progressLayer)
}
private func updateProgress() {
CATransaction.begin()
CATransaction.setAnimationDuration(0.3)
progressLayer.strokeEnd = progress
CATransaction.commit()
}
}</code></pre>
<pre><code class="lang-swift">// ios/CircularProgressViewManager.swift
import React
@objc(CircularProgressViewManager)
class CircularProgressViewManager: RCTViewManager {
override static func requiresMainQueueSetup() -&gt; Bool {
return true // UI components need main thread
}
override func view() -&gt; UIView! {
return CircularProgressView()
}
}</code></pre>
<pre><code class="lang-objective-c">// ios/CircularProgressViewManager.m
#import &lt;React/RCTViewManager.h&gt;
@interface RCT_EXTERN_MODULE(CircularProgressViewManager, RCTViewManager)
RCT_EXPORT_VIEW_PROPERTY(progress, CGFloat)
RCT_EXPORT_VIEW_PROPERTY(progressColor, UIColor)
RCT_EXPORT_VIEW_PROPERTY(trackColor, UIColor)
@end</code></pre>
<pre><code class="lang-typescript">// src/components/CircularProgress.tsx
import React from &#x27;react&#x27;;
import { requireNativeComponent, ViewProps } from &#x27;react-native&#x27;;
interface CircularProgressProps extends ViewProps {
progress: number; // 0.0 - 1.0
progressColor?: string;
trackColor?: string;
}
const NativeCircularProgress = requireNativeComponent&lt;CircularProgressProps&gt;(
&#x27;CircularProgressView&#x27;
);
export const CircularProgress: React.FC&lt;CircularProgressProps&gt; = (props) =&gt; {
return &lt;NativeCircularProgress {...props} /&gt;;
};</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Native iOS animations and rendering</li><li>Full access to UIKit components</li><li>Performance for complex UI</li><li>Reusable across React Native apps</li></ul>
<h3>Pattern 4: Async Native Operations with Error Handling</h3>
<pre><code class="lang-swift">// ios/NetworkModule.swift
import Foundation
import React
@objc(NetworkModule)
class NetworkModule: NSObject {
@objc
static func requiresMainQueueSetup() -&gt; Bool {
return false
}
@objc
func fetchUser(_ userId: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {
guard let url = URL(string: &quot;https://api.example.com/users/\(userId)&quot;) else {
rejecter(&quot;INVALID_URL&quot;, &quot;Invalid user ID&quot;, nil)
return
}
URLSession.shared.dataTask(with: url) { data, response, error in
// Handle network error
if let error = error {
rejecter(&quot;NETWORK_ERROR&quot;, error.localizedDescription, error)
return
}
// Handle HTTP error
guard let httpResponse = response as? HTTPURLResponse else {
rejecter(&quot;INVALID_RESPONSE&quot;, &quot;Invalid response type&quot;, nil)
return
}
guard (200...299).contains(httpResponse.statusCode) else {
rejecter(&quot;HTTP_ERROR&quot;, &quot;Status code: \(httpResponse.statusCode)&quot;, nil)
return
}
// Parse JSON
guard let data = data else {
rejecter(&quot;NO_DATA&quot;, &quot;No data received&quot;, nil)
return
}
do {
let json = try JSONSerialization.jsonObject(with: data, options: [])
resolver(json)
} catch {
rejecter(&quot;PARSE_ERROR&quot;, &quot;Failed to parse JSON&quot;, error)
}
}.resume()
}
}</code></pre>
<pre><code class="lang-typescript">// src/modules/NetworkModule.ts
import { NativeModules } from &#x27;react-native&#x27;;
interface User {
id: string;
name: string;
email: string;
}
class NetworkModuleWrapper {
async fetchUser(userId: string): Promise&lt;User&gt; {
try {
const user = await NativeModules.NetworkModule.fetchUser(userId);
return user as User;
} catch (error: any) {
// Error codes from native module
switch (error.code) {
case &#x27;INVALID_URL&#x27;:
throw new Error(&#x27;Invalid user ID format&#x27;);
case &#x27;NETWORK_ERROR&#x27;:
throw new Error(&#x27;Network connection failed&#x27;);
case &#x27;HTTP_ERROR&#x27;:
throw new Error(`Server error: ${error.message}`);
case &#x27;PARSE_ERROR&#x27;:
throw new Error(&#x27;Invalid response format&#x27;);
default:
throw error;
}
}
}
}
export default new NetworkModuleWrapper();</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Network requests with iOS URLSession</li><li>File system operations</li><li>Database queries</li><li>Any async native operation</li></ul>
<h3>Pattern 5: Swift Concurrency Integration</h3>
<pre><code class="lang-swift">// ios/ModernAsyncModule.swift
import Foundation
import React
@objc(ModernAsyncModule)
class ModernAsyncModule: NSObject {
@objc
static func requiresMainQueueSetup() -&gt; Bool {
return false
}
@objc
func performAsyncWork(_ input: String, resolver: @escaping RCTPromiseResolveBlock, rejecter: @escaping RCTPromiseRejectBlock) {
Task {
do {
let result = try await processData(input)
resolver(result)
} catch {
rejecter(&quot;ASYNC_ERROR&quot;, error.localizedDescription, error)
}
}
}
private func processData(_ input: String) async throws -&gt; [String: Any] {
// Simulate async work
try await Task.sleep(nanoseconds: 1_000_000_000)
// Use structured concurrency
async let part1 = fetchPart1(input)
async let part2 = fetchPart2(input)
let results = try await [part1, part2]
return [
&quot;input&quot;: input,
&quot;results&quot;: results,
&quot;timestamp&quot;: Date().timeIntervalSince1970
]
}
private func fetchPart1(_ input: String) async throws -&gt; String {
try await Task.sleep(nanoseconds: 500_000_000)
return &quot;Part1: \(input)&quot;
}
private func fetchPart2(_ input: String) async throws -&gt; String {
try await Task.sleep(nanoseconds: 500_000_000)
return &quot;Part2: \(input)&quot;
}
}</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>Modern Swift async/await syntax</li><li>Structured concurrency patterns</li><li>Better error handling</li><li>Cancellation support</li></ul>
<h3>Pattern 6: Objective-C Native Module (Legacy)</h3>
<pre><code class="lang-objective-c">// ios/LegacyModule.h
#import &lt;React/RCTBridgeModule.h&gt;
@interface LegacyModule : NSObject &lt;RCTBridgeModule&gt;
@end</code></pre>
<pre><code class="lang-objective-c">// ios/LegacyModule.m
#import &quot;LegacyModule.h&quot;
@implementation LegacyModule
RCT_EXPORT_MODULE();
RCT_EXPORT_METHOD(addNumbers:(NSInteger)a
b:(NSInteger)b
resolver:(RCTPromiseResolveBlock)resolve
rejecter:(RCTPromiseRejectBlock)reject)
{
NSInteger sum = a + b;
resolve(@(sum));
}
RCT_EXPORT_METHOD(performCallback:(RCTResponseSenderBlock)callback)
{
callback(@[[NSNull null], @&quot;Success&quot;]);
}
+ (BOOL)requiresMainQueueSetup
{
return NO;
}
@end</code></pre>
<p><strong>When to use</strong>:</p>
<ul><li>Legacy codebases</li><li>Existing Objective-C libraries</li><li>Team familiar with Objective-C</li><li>Interoperating with C/C++ code</li></ul>
<hr>
<h2>Quick Reference</h2>
<h3>Bridge Data Types</h3>
<pre><code>JavaScript Type | Objective-C/Swift Type | Notes
-------------------|------------------------------|------------------
number | NSNumber / Double / Int | Auto-converted
string | NSString / String | UTF-8 encoded
boolean | NSNumber / Bool | true/false
null/undefined | NSNull / nil | Check for NSNull
Array | NSArray / [Any] | Ordered collection
Object | NSDictionary / [String: Any] | Key-value pairs
Function | RCTResponseSenderBlock | Callback
Promise | RCTPromise(Resolve/Reject) | Async result</code></pre>
<h3>Module Export Macros</h3>
<pre><code class="lang-objective-c">RCT_EXPORT_MODULE() // Export module with class name
RCT_EXPORT_MODULE(CustomName) // Export with custom name
RCT_EXPORT_METHOD(methodName:...) // Export async method
RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD() // Export synchronous method
RCT_EXPORT_VIEW_PROPERTY(name, type) // Export view property</code></pre>
<h3>Best Practices</h3>
<pre><code>✅ DO: Use promises for async operations
✅ DO: Validate input parameters
✅ DO: Return descriptive error codes
✅ DO: Run on background thread when possible
✅ DO: Use type-safe TypeScript interfaces
❌ DON&#x27;T: Block the main thread with heavy operations
❌ DON&#x27;T: Return functions or callbacks from native
❌ DON&#x27;T: Store references to JavaScript objects
❌ DON&#x27;T: Use synchronous methods for slow operations
❌ DON&#x27;T: Forget to handle errors properly</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Synchronous heavy operations</strong>: Blocking main thread with slow native code ✅ Use promises and background threads: <code>requiresMainQueueSetup() -&gt; false</code></p>
<p>❌ <strong>Over-bridging</strong>: Calling native for simple logic better done in JS ✅ Use native only for platform APIs, performance-critical code, or third-party SDKs</p>
<p>❌ <strong>No error handling</strong>: Native errors crash the app ✅ Always use try-catch and reject promises with descriptive error codes</p>
<p>❌ <strong>Storing JavaScript callbacks</strong>: Memory leaks and crashes ✅ Use event emitters for continuous updates, promises for one-time results</p>
<p>❌ <strong>Large data serialization</strong>: Sending MB of data across bridge ✅ Use file paths or shared memory, send only metadata</p>
<p>❌ <strong>Main thread for async work</strong>: UI freezes during operations ✅ Use background threads for network, file I/O, computations</p>
<p>❌ <strong>Missing TypeScript types</strong>: Untyped native module usage ✅ Create interfaces for all native modules with full type safety</p>
<p>❌ <strong>Not cleaning up resources</strong>: Memory leaks from sensors, timers, etc. ✅ Implement <code>stopObserving</code> and cleanup in <code>dealloc</code>/<code>deinit</code></p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>react-native-setup.md</code> - Project configuration for native modules</li><li><code>react-native-performance.md</code> - Optimizing bridge communication</li><li><code>swift-concurrency.md</code> - Modern Swift async patterns</li><li><code>ios-networking.md</code> - URLSession and network best practices</li><li><code>swiftui-architecture.md</code> - iOS app structure and patterns</li><li><code>ios-testing.md</code> - Testing native modules</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/mobile-react-native-native-modules.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>