AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

react-native-best-practices

Provides React Native performance optimization guidelines for FPS, TTI, bundle size, memory leaks, re-renders, and animations. Applies to tasks involving Hermes optimization, JS thread blocking, bridge overhead, FlashList, native modules, or debugging jank and frame drops.

Original source
callstackincubator
License
MIT
Pinned revision
59e9d17446a248b21d86f078fcd0bd2d36db1ca4

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read callstackincubator--react-native-best-practices at revision 59e9d17446a248b21d86f078fcd0bd2d36db1ca4, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 31

references/native-threading-model.md


title: Threading Model impact: HIGH tags: threads, turbo-modules, fabric, async, sync

Skill: Threading Model

Understand which threads Turbo Modules and Fabric use for initialization, method calls, and view updates.

Quick Reference

Thread names and exact scheduling can vary by React Native version, architecture, and host app setup. Use this as a default mental model, then confirm with a profiler when the exact thread matters.

| Action | Default assumption | |--------|--------------------| | UI view creation/updates | Main/UI thread | | Sync value-returning Turbo Module method | Blocks the JS caller until it returns | | Async Turbo Module method | Does not block JS, but may run on a shared native modules executor | | Heavy CPU/I/O work | Move to a module-owned background queue/coroutine |

Key rule: Sync methods should be trivial and deterministic. Move anything that can block, allocate heavily, perform I/O, or wait on locks to async/background work.

When to Use

  • Building native modules
  • Debugging threading issues
  • Accessing UI from native code
  • Understanding async vs sync method behavior

Available Threads

| Thread | Name in Debugger | Purpose | |--------|------------------|---------| | Main/UI | Main thread | UI rendering, UIKit/Android Views | | JavaScript | mqt_v_js | JS execution, React | | Native Modules | mqt_v_native | Async Turbo Module calls | | Custom | Various | Your background threads |

Turbo Modules Threading

Initialization

| Platform | Thread | Notes | |----------|--------|-------| | iOS | Main thread | Assumes UIKit access needed | | Android (lazy) | JS thread | Default behavior | | Android (eager) | Native modules thread | When needsEagerInit = true |

iOS: React Native runs init on main thread assuming UIKit access.

Android Eager Loading:

// ReactModuleInfo constructor params:
// canOverrideExistingModule, needsEagerInit, isCxxModule, isTurboModule
ReactModuleInfo(
    AwesomeModule.NAME,
    AwesomeModule.NAME,
    false,
    true,   // needsEagerInit = true → runs on native modules thread
    false,
    true
)

Synchronous Method Calls

Synchronous value-returning Turbo Module methods block the JS caller until they return. Treat them as JS-critical even if a platform implementation dispatches through an internal executor.

// iOS - runs on JS thread
@objc func multiply(_ a: Double, b: Double) -> NSNumber {
    // This blocks JS for entire duration!
    return a * b as NSNumber
}

Danger: Long sync operations freeze the app:

// BAD: Blocks JS for 20 seconds
@objc func multiply(_ a: Double, b: Double) -> NSNumber {
    Thread.sleep(forTimeInterval: 20)  // App frozen!
    return a * b as NSNumber
}

Asynchronous Method Calls

Usually dispatched off the JS thread - does not block JS while the native work is pending.

The native modules thread is shared across modules. If async work is CPU-heavy or long-running, move it to a module-owned queue/coroutine scope rather than occupying the shared React Native native modules thread.

// iOS - runs on mqt_v_native thread
@objc func asyncOperation(
    _ a: Double,
    resolve: @escaping RCTPromiseResolveBlock,
    reject: RCTPromiseRejectBlock
) {
    // Already on background thread
    resolve(a * 2)
}
// Android - runs on native modules thread
override fun asyncOperation(a: Double, promise: Promise?) {
    // Already on background thread
    promise?.resolve(a * 2)
}

Module Invalidation

Called when React Native instance is torn down (e.g., Metro reload):

| Platform | Thread | |----------|--------| | iOS | Native modules thread | | Android | ReactHost thread pool |

iOS: Implement RCTInvalidating protocol.

Fabric (Native Views) Threading

View Lifecycle

| Operation | Default assumption | |-----------|--------------------| | View init | Main thread | | Prop updates | Main thread | | Layout/shadow tree work | Architecture-dependent; profile before assuming thread ownership |

Views always manipulate UI on main thread (UIKit/Android requirement).

Do not use a hard-coded "Yoga runs on X thread" rule when diagnosing performance. React Native's renderer and scheduler details change across New Architecture releases; use Instruments, Perfetto, or Android Studio profiler to identify the actual bottleneck.

Moving Work to Background

iOS: DispatchQueue

@objc func heavyWork(
    resolve: @escaping RCTPromiseResolveBlock,
    reject: RCTPromiseRejectBlock
) {
    DispatchQueue.global().async {
        // Heavy computation here
        let result = self.compute()
        resolve(result)
    }
}

Android: Coroutines

class MyModule(reactContext: ReactApplicationContext) :
    NativeMyModuleSpec(reactContext) {
    
    private val moduleScope = CoroutineScope(Dispatchers.Default + SupervisorJob())
    
    override fun heavyWork(promise: Promise?) {
        moduleScope.launch {
            // Heavy computation here
            val result = compute()
            promise?.resolve(result)
        }
    }
    
    override fun invalidate() {
        super.invalidate()
        moduleScope.cancel()  // Important: cancel to prevent leaks
    }
}

Thread Safety Checklist

| Scenario | Safe? | Solution | |----------|-------|----------| | Sync method accessing shared state | ⚠️ | Use locks/synchronized | | Async method accessing UI | ❌ | Dispatch to main thread | | Multiple async calls to same resource | ⚠️ | Queue or mutex | | Accessing JS from background | ❌ | Use CallInvoker |

Accessing UI from Background (iOS)

DispatchQueue.global().async {
    let result = self.heavyComputation()
    
    DispatchQueue.main.async {
        // Safe to update UI here
        self.updateUI(with: result)
    }
}

Accessing UI from Background (Android)

moduleScope.launch(Dispatchers.Default) {
    val result = heavyComputation()
    
    withContext(Dispatchers.Main) {
        // Safe to update UI here
        updateUI(result)
    }
}

Summary Table

| Action | iOS Thread | Android Thread | |--------|------------|----------------| | Module init | Version/setup dependent; avoid blocking | Version/setup dependent; avoid blocking | | Sync method | Blocks JS caller | Blocks JS caller | | Async method | Shared native executor or implementation-defined | Shared native executor or implementation-defined | | View init | Main | Main | | Prop update | Main | Main | | Yoga/layout | Profile; do not assume fixed ownership | Profile; do not assume fixed ownership | | Invalidate | Native modules | ReactHost pool |

Related Skills