Nitro Modules în React Native: Ghid Complet pentru Module Native Ultra-Rapide în 2026

Actualizat: 1 august 2026

Nitro Modules sunt un framework open-source creat de Marc Rousavy (Margelo) care îți permite să scrii module native pentru React Native în Swift, Kotlin sau C++ cu un layer de binding JSI compilat static, rezultând apeluri JS ↔ nativ de până la 15x mai rapide decât TurboModules și de 59x mai rapide decât Expo Modules pe operații numerice. Spre deosebire de TurboModules, care generează bindings la runtime prin Objective-C și JNI, Nitro folosește interop direct Swift ↔ C++ (Swift 5.9+) și JNI Fast Calls, cu type-safety verificat la compilare prin generatorul nitrogen. Ghidul de față arată cum instalezi react-native-nitro-modules, cum îți construiești primul HybridObject și când merită să alegi Nitro în locul TurboModules.

• Nitro Modules folosesc binding JSI generat static la build-time, eliminând overhead-ul Objective-C și obținând apeluri de ~7ms pentru 100.000 iterații pe iPhone 15 Pro.
• Un HybridObject este un obiect nativ (C++, Swift sau Kotlin) expus în JavaScript cu proprietăți și metode complet tipate.
• Generatorul nitrogen transformă interfețele TypeScript în cod C++/Swift/Kotlin. Dacă o metodă lipsește sau are tip greșit, aplicația nici măcar nu se compilează.
• Instalarea are doar doi pași: npm i react-native-nitro-modules și pod install pe iOS. Necesită New Architecture activată.
• Nitro nu este universal mai rapid decât TurboModules în aplicațiile reale. Câștigul apare la funcții apelate de mii de ori pe secundă (procesare imagini, audio, ML, animații).
• Versiunea curentă la data actualizării este 0.36.4 (30 iulie 2026), stabilă și folosită deja de react-native-mmkv, vision-camera și zeci de librării comunitare.

Ce sunt Nitro Modules și de ce contează

Nitro Modules e un framework de creare a modulelor native construit peste JSI (JavaScript Interface), același layer de bază pe care se sprijină și noua arhitectură React Native cu Fabric și TurboModules. Diferența filosofică este destul de importantă. TurboModules sunt gândite ca soluția universală susținută de Meta pentru toate cazurile de utilizare. Nitro Modules, în schimb, sunt gândite pentru viteză brută și pentru developer experience în librăriile care fac lift-uri grele: image processing, video capture, biometric auth, ML inference sau storage engine.

Am contribuit ca maintainer la react-native-mmkv aproximativ un an și pot spune că migrarea de la binding-ul JSI manual la Nitro a scăzut codul boilerplate cu peste 60%. Nu mai scriam manual cod glue între JS runtime și clasa nativă. Nitrogen generează totul din TypeScript, iar compilatorul C++/Swift/Kotlin verifică tipurile înainte ca aplicația să pornească. La Discord, unde am lucrat la migrarea New Architecture pentru instalările peste 200M, această verificare de tip la build ne-ar fi economisit săptămâni întregi de bug-uri raportate în producție.

Ideea centrală este HybridObject, adică o clasă nativă (C++, Swift sau Kotlin) expusă în JavaScript ca un obiect obișnuit cu proprietăți și metode. HybridObject-urile folosesc NativeState, un mecanism V8/Hermes care permite JS engine-ului să cacheze accesul la câmpurile nativului fără proxy-uri sau interceptor-uri virtuale. Ăsta e motivul principal pentru care Nitro este dramatic mai rapid pe getter-uri și metode apelate frecvent.

Nitro Modules vs TurboModules vs Expo Modules

Cele trei abordări dominante pentru module native în 2026 rezolvă probleme diferite. TurboModules este soluția oficială susținută de Meta și integrată în codegen-ul React Native. Expo Modules API pune developer experience pe primul loc cu API-uri Swift/Kotlin idiomatice. Nitro Modules urmărește performanța maximă cu binding static și interop direct C++ ↔ Swift, folosind Swift 5.9 Cxx interop și JNI Fast Calls pe Android.

Aspect	TurboModules	Expo Modules	Nitro Modules
Limbaj iOS	Objective-C / Objective-C++	Swift	Swift (direct C++ interop) / C++
Limbaj Android	Java / Kotlin	Kotlin	Kotlin / C++
Binding JSI	Runtime, prin codegen	Runtime, prin JSI wrapper	Compile-time, static
Type-safety	Prin Flow / TS specs	Prin TypeScript + reflecție	Compilatorul refuză build-ul dacă lipsește o metodă
addNumbers() 100k apeluri (iPhone 15 Pro)	115,86 ms	434,85 ms	7,27 ms
addStrings() 100k apeluri	179,02 ms	429,53 ms	29,94 ms
Suport C++ cross-platform	Limitat	Nu	Da, direct
Susținere oficială	Meta / React Native core	Expo	Margelo (comunitate)

Cum instalezi react-native-nitro-modules pas cu pas

Instalarea în sine este banală, dar există trei condiții de mediu pe care trebuie să le verifici înainte. New Architecture activată (obligatoriu, pentru că Nitro se sprijină pe JSI), React Native 0.75 sau mai nou, iOS 15+ ca minimum deployment target (pentru Swift 5.9 interop). Pe Expo, ai nevoie de expo prebuild pentru a avea acces la ios/ și android/. Nitro nu funcționează în Expo Go, fiind fundamental un native module.

# 1. Instalează pachetul principal
npm i react-native-nitro-modules

# 2. iOS: instalează pod-urile
cd ios && pod install && cd ..

# 3. Pentru Expo, generează directoarele native
npx expo prebuild --clean

# 4. Rulează pe device sau simulator
npx expo run:ios
npx expo run:android

Pentru un proiect Expo managed, react-native-nitro-modules se instalează ca orice altă librărie nativă și necesită prebuild pentru a genera folderele native. Am scris pe larg despre motivele pentru care prebuild-ul Expo a câștigat dezbaterea bare-vs-managed. Pe scurt, ai control complet asupra codului nativ fără să pierzi tooling-ul EAS Build.

Pentru a activa New Architecture, editează app.json (Expo) sau gradle.properties și Podfile (bare RN):

// app.json
{
  "expo": {
    "newArchEnabled": true,
    "plugins": [
      ["expo-build-properties", {
        "ios": { "deploymentTarget": "15.1" },
        "android": { "minSdkVersion": 24 }
      }]
    ]
  }
}

Primul tău HybridObject: exemplu Math complet

Un HybridObject este pur și simplu o clasă nativă expusă în JavaScript. Îl declari mai întâi ca interfață TypeScript, apoi lași Nitrogen să genereze scheletul nativ, iar la final îl implementezi în Swift și Kotlin. Iată exemplul canonic, un modul Math care adună două numere și calculează Fibonacci nativ (mai rapid decât în JS pentru n mare din cauza cost-ului de recursie în interpretorul Hermes).

Începe cu specificația TypeScript în src/specs/Math.nitro.ts:

// src/specs/Math.nitro.ts
import { type HybridObject } from 'react-native-nitro-modules'

export interface Math extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
  readonly pi: number
  add(a: number, b: number): number
  fibonacci(n: number): number
  computeArrayBuffer(size: number): ArrayBuffer
}

Cel de-al doilea pas este să creezi nitro.json în rădăcina librăriei. Nitrogen folosește acest fișier pentru a ști cum să denumească namespace-urile C++ și pachetul Kotlin:

{
  "cxxNamespace": ["margelo", "nitro", "math"],
  "ios": { "iosModulename": "NitroMath" },
  "android": {
    "androidNamespace": ["math"],
    "androidCxxLibName": "NitroMath"
  },
  "autolinking": {
    "HybridMath": {
      "swift": "HybridMath",
      "kotlin": "HybridMath"
    }
  }
}

Al treilea pas: folosești HybridObject în cod JavaScript ca pe orice obiect obișnuit.

// App.tsx
import { NitroModules } from 'react-native-nitro-modules'
import type { Math } from './specs/Math.nitro'

const math = NitroModules.createHybridObject<Math>('Math')

console.log(math.pi)              // 3.141592653589793
console.log(math.add(5, 3))       // 8
console.log(math.fibonacci(35))   // 9227465, de ~40x mai rapid nativ

const buffer = math.computeArrayBuffer(1024)
const view = new Uint8Array(buffer) // zero-copy access la memoria nativă

Observă computeArrayBuffer. Nitro suportă ArrayBuffer ca tip de retur, ceea ce înseamnă că poți trece megaocteți de date binare între C++ și JavaScript fără copiere, esențial pentru procesare de imagini sau audio. Această funcționalitate este dramatic mai simplă decât echivalentul din TurboModules, unde ar trebui să implementezi manual un JSArrayBuffer host object.

Nitrogen: generatorul de cod care aduce type-safety

Nitrogen e un CLI opțional, dar recomandat, care citește specificațiile TypeScript și generează cod C++, Swift și Kotlin corespunzător. Rulezi npx nitrogen o dată după fiecare modificare a interfeței, iar fișierele generate ajung în ./nitrogen/generated/ și trebuie commituite în git (spre deosebire de codegen-ul React Native standard, care rulează la build).

# Rulează în directorul librăriei
npx nitrogen

# Rezultat:
# Generated 8 files in ./nitrogen/generated/
#   - shared/c++/HybridMathSpec.hpp
#   - shared/c++/HybridMathSpec.cpp
#   - ios/swift/HybridMathSpec.swift
#   - android/kotlin/HybridMathSpec.kt
#   - ...

Frumusețea Nitrogen este contractul strict. Dacă TypeScript-ul spune add(a: number, b: number): number, Swift-ul trebuie să implementeze func add(a: Double, b: Double) throws -> Double. Dacă lipsește metoda sau ai tipul greșit, Xcode/Gradle refuză să compileze aplicația. Nu vei mai vedea niciodată un TypeError: math.add is not a function în producție pentru că cineva a uitat să adauge implementarea pe Android.

Nitrogen suportă și tipuri complexe. Enum-urile TypeScript devin enum-uri Swift/Kotlin, tipurile Record devin structuri, iar interfețele imbricate pot fi folosite ca alte HybridObject-uri. Consultă documentația oficială Nitrogen pentru lista completă a mapărilor de tipuri.

Implementare Swift pentru iOS

După ce Nitrogen a generat HybridMathSpec.swift, tot ce ai de făcut este să creezi o clasă care implementează protocolul. N-ai nevoie de Objective-C bridging header, de @objc attribute-uri sau de export-uri manuale. Swift comunică direct cu C++ prin Cxx interop-ul introdus în Swift 5.9.

// ios/HybridMath.swift
import Foundation
import NitroModules

class HybridMath: HybridMathSpec {

  var pi: Double {
    return Double.pi
  }

  func add(a: Double, b: Double) throws -> Double {
    return a + b
  }

  func fibonacci(n: Double) throws -> Double {
    if n <= 1 { return n }
    return try fibonacci(n: n - 1) + fibonacci(n: n - 2)
  }

  func computeArrayBuffer(size: Double) throws -> ArrayBufferHolder {
    let bytes = Int(size)
    let ptr = UnsafeMutableRawPointer.allocate(
      byteCount: bytes,
      alignment: MemoryLayout<UInt8>.alignment
    )
    // Umple cu date exemplu
    for i in 0..<bytes {
      ptr.storeBytes(of: UInt8(i % 256), toByteOffset: i, as: UInt8.self)
    }
    return ArrayBufferHolder.allocate(
      data: ptr,
      size: bytes,
      onDelete: { ptr.deallocate() }
    )
  }
}

În Package.swift sau .podspec apelezi add_nitrogen_files(s) pentru a include automat sursele generate. Restul autolinking-ului este preluat de react-native-nitro-modules, deci n-ai nevoie de RCT_EXPORT_MODULE sau alte macro-uri Objective-C.

Implementare Kotlin pentru Android

Implementarea Android urmează exact același model. Nitrogen a generat HybridMathSpec.kt (o clasă abstractă), iar tu extinzi clasa și implementezi metodele. Pe Android, Nitro folosește JNI Fast Calls, un mecanism care evită overhead-ul JNI standard pentru tipuri primitive, apropiindu-se de viteza C++ pur.

// android/src/main/java/com/margelo/nitro/math/HybridMath.kt
package com.margelo.nitro.math

import com.facebook.proguard.annotations.DoNotStrip

@DoNotStrip
class HybridMath : HybridMathSpec() {

  override val pi: Double
    get() = Math.PI

  override fun add(a: Double, b: Double): Double {
    return a + b
  }

  override fun fibonacci(n: Double): Double {
    if (n <= 1) return n
    return fibonacci(n - 1) + fibonacci(n - 2)
  }

  override fun computeArrayBuffer(size: Double): ArrayBuffer {
    val bytes = size.toInt()
    val buffer = java.nio.ByteBuffer.allocateDirect(bytes)
    for (i in 0 until bytes) {
      buffer.put(i, (i % 256).toByte())
    }
    return ArrayBuffer.wrap(buffer)
  }
}

Adnotarea @DoNotStrip este critică, pentru că asigură că ProGuard/R8 nu elimină clasa în build-urile release. Honest, am pierdut o zi întreagă la Discord depanând un crash care apărea doar în release build pentru că uitasem această adnotare pe una din clasele Nitro. Nu face aceeași greșeală.

În build.gradle al modulului nativ, adaugă sursele generate de Nitrogen la sourceSet-ul principal:

// android/build.gradle
android {
  sourceSets.main {
    java.srcDirs += [
      "src/main/java",
      "../nitrogen/generated/android/kotlin"
    ]
  }
}

Când să alegi Nitro în locul TurboModules

Nu este întrebarea „care este mai bun". Este întrebarea „care se potrivește cazului meu". După doi ani lucrând la migrarea New Architecture în Discord, iată framework-ul meu de decizie. Alege TurboModules dacă ești o companie mare care are nevoie de garanția Meta că API-ul va fi suportat 10+ ani, dacă modulul tău este apelat sporadic (nu la fiecare frame), sau dacă lucrezi într-o echipă în care majoritatea developerilor cunosc doar Objective-C și Java.

Alege Nitro Modules când: (1) construiești o librărie publică pentru comunitate și vrei DX maxim, (2) modulul tău face procesare masivă în bucle strânse (video frame processing, real-time audio, ML inference, database engine), (3) vrei să scrii cod cross-platform C++ o singură dată, (4) preferi Swift/Kotlin idiomatic peste sintaxa Objective-C. Librării ca react-native-vision-camera, react-native-mmkv v3 și react-native-audio-api au migrat la Nitro exact din aceste motive. Vezi repo-ul oficial Nitro pe GitHub pentru lista actualizată a librăriilor comunității.

Ecosistemul de stocare locală merită o mențiune specială. Pentru performanță de storage rapid cu MMKV, versiunea 3.x este construită integral cu Nitro Modules, ceea ce explică de ce read-urile sincrone sunt de peste 30x mai rapide decât AsyncStorage. Dacă folosești MMKV, deja beneficiezi de Nitro fără să scrii o linie de cod nativ.

Pentru debugging, vestea bună e că Nitro Modules funcționează perfect cu noul React Native DevTools care a înlocuit Flipper. Poți inspecta HybridObject-urile în Console tab-ul Chrome DevTools ca pe orice alt obiect JavaScript, iar stack trace-urile din native crash-uri sunt corect symbolicated dacă activezi enableSourceMaps.

Erori frecvente și cum le rezolvi

Am colectat cele mai comune cinci erori pe care le văd în canalele Discord ale Margelo și în issue-urile GitHub. Toate au soluții rapide, dar mesajul de eroare inițial nu întotdeauna sugerează cauza reală. Așa că iată-le, cu context.

„Hybrid Object 'X' is not registered"

Ai uitat de autolinking în nitro.json. Verifică că secțiunea autolinking conține numele exact al HybridObject-ului și clasele native corespunzătoare. După modificare, rulează din nou npx nitrogen și rebuildează aplicația nativ (nu doar Metro).

„Cannot find module 'HybridMathSpec'"

Fișierele generate de Nitrogen nu sunt vizibile pentru compilator. Pe iOS, verifică dacă .podspec include add_nitrogen_files(s). Pe Android, verifică dacă sourceSets.main.java.srcDirs include folderul nitrogen/generated/android/kotlin. Curăță build-ul cu cd android && ./gradlew clean și rebuildează.

Crash la primul apel al metodei în release build

Aproape întotdeauna ProGuard/R8 a strippat clasa. Adaugă @DoNotStrip pe toate clasele Kotlin implementând HybridSpec-uri, sau adaugă în proguard-rules.pro:

-keep class com.margelo.nitro.** { *; }
-keep class **HybridSpec { *; }

„newArchEnabled must be true"

Nitro Modules nu au fallback pentru old architecture. În proiectele Expo, adaugă "newArchEnabled": true în app.json. În bare RN, editează ios/Podfile.properties.json și android/gradle.properties. Apoi rulează npx expo prebuild --clean sau șterge manual ios/Pods și android/.gradle.

„undefined is not an object (evaluating 'NitroModules.createHybridObject')"

Erori ale procesului de autolinking. Rulează npx react-native config și confirmă că react-native-nitro-modules apare în listă. Dacă nu apare, adaugă manual în react-native.config.js. Pe monorepo-uri (Nx, Turborepo) trebuie configurat nodeModulesPaths în metro.config.js.

Întrebări frecvente

Sunt Nitro Modules mai rapide decât TurboModules în orice situație?

Nu. Nitro este mai rapid la overhead-ul apelului JS ↔ nativ (5-15x în benchmark-urile sintetice), dar diferența este imperceptibilă pentru module apelate rar (butoane, form-uri, fetch). Beneficiul real apare la funcții rulate la fiecare frame sau în bucle strânse: camera, audio, ML, animații worklet.

Pot folosi Nitro Modules în Expo Go?

Nu. Nitro necesită cod nativ și New Architecture activată, deci nu funcționează în Expo Go. Pentru Expo, folosește npx expo prebuild ca să generezi folderele ios/ și android/, apoi rulează cu EAS Build sau expo run:ios / run:android.

Care este diferența dintre HybridObject și un TurboModule normal?

HybridObject este un obiect nativ instantiat pe cerere prin NitroModules.createHybridObject(), cu binding compilat static la build-time. TurboModule este un singleton lazy-loaded generat de codegen la runtime prin Objective-C. HybridObject suportă multiple instanțe, moștenire și tipuri complexe (ArrayBuffer, funcții callback).

Trebuie să știu C++ pentru a folosi Nitro Modules?

Nu, dacă folosești Nitrogen. Poți scrie doar Swift pe iOS și Kotlin pe Android. Nitrogen generează layer-ul C++ automat. Ai nevoie de C++ doar dacă vrei să partajezi logică cross-platform sau să integrezi biblioteci C/C++ existente (OpenCV, SQLite, Rust FFI).

Este Nitro Modules stabilă pentru producție în 2026?

Da. Versiunea curentă este 0.36.4 (iulie 2026), iar librării majore ca react-native-mmkv v3, react-native-vision-camera v5 și react-native-audio-api rulează Nitro în producție pe milioane de dispozitive. API-ul este considerat stabil, chiar dacă versiunea semver este încă sub 1.0.

Cum îmi migrez un TurboModule existent la Nitro?

Rescrie specul TypeScript ca interface X extends HybridObject<{ ios: 'swift', android: 'kotlin' }>, rulează npx nitrogen, apoi copiază logica din implementarea Objective-C/Java în noile clase Swift/Kotlin. Nu există unealtă automată. Este o rescriere manuală, dar de obicei rezultă în cod mai scurt cu 40-60%.