Nitro Modules

Nitro is a framework for building high-performance native modules for JavaScript. It allows you to implement JavaScript objects in C++, Swift, or Kotlin instead of JS.

Key abstractions:

• Nitro Module: A library built with Nitro containing one or more Hybrid Objects.
• Hybrid Object: A native object implemented in C++, Swift, or Kotlin that can be accessed directly from JS.
• Nitrogen: An optional code-generator that creates native bindings from TypeScript interfaces, ensuring type safety between JS and native code.

Nitro is primarily designed for React Native but works in any environment using JSI (JavaScript Interface).

Nitro Modules are fast, type-safe native modules for React Native that use statically compiled bindings to JSI (JavaScript Interface). The ecosystem consists of two primary components:

• react-native-nitro-modules: The core C++ library that powers all nitro modules.
• nitrogen: An optional code-generator designed for library authors to streamline the creation of nitro modules.

Nitrogen is Nitro's code-generator. It uses an AST parser to read TypeScript definitions and automatically generate native interfaces (C++, Swift, and Kotlin) for React Native Nitro Modules.

Key Benefits:

• Type-Safety: If the native implementation does not match the TypeScript spec (e.g., missing methods or incorrect types), the app will fail to compile.
• Automation: It handles the boilerplate of creating cross-platform bindings.

When to use it:

• Library Authors: Should use Nitrogen to generate specs and commit the generated files to their repository. This ensures users of the library don't need to run Nitrogen themselves.
• App Developers: If you are consuming a library already built with Nitro, you do not need to run Nitrogen.

Hybrid Objects from your Nitro Module are registered in the HybridObjectRegistry. This registration must be triggered by calling .initializeNative(). The location of this call depends on your environment:

• In React Native: This is typically handled in your *Package.kt file, which calls .initializeNative().
• Outside of React Native: You must manually call .initializeNative() within your library's entry point.

Since Int64 and UInt64 are limited to 64-bit ranges, you must use alternative strategies to represent JS bigint values that exceed these bounds:

1. String passing: Pass the bigint as a string and deserialize it on the native side.
2. Custom Types: Implement a custom big integer type and use a JSIConverter to handle the conversion between your custom type and a JS bigint.

Nitro statically enforces that Promises must always be resolved or rejected. You cannot exit a function that returns a Promise<T> without returning a valid Promise instance. This prevents bugs where a developer might accidentally return void or exit early without fulfilling the promise contract.

func saveToFile(image: HybridImage) -> Promise<Void> {
  guard let data = image.data else { return } // code-error: Cannot return void!
  return Promise.async {
    try await data.writeToFile("file://tmp/img.png")
  }
}

Because Nitro Modules are object-oriented, HybridObject instances are first-class citizens that can be passed between JavaScript and native code. This allows you to define interfaces in TypeScript that multiple native implementations can satisfy.

For example, you can define an Image interface. On the native side, you can have multiple classes (e.g., HybridUIImage, HybridCGImage, or HybridBufferImage) that all implement the same HybridImageSpec. This allows other native or JS functions (like a Cropper) to accept any object that conforms to that specification, regardless of its underlying data storage.

interface Image
  extends HybridObject<{ ios: 'swift' }> {
  readonly width: number
  readonly height: number
}

interface Camera
  extends HybridObject<{ ios: 'swift' }> {
  takePhoto(): Image
}

Any TypeScript interface or type that does not extend HybridObject is represented as a fully type-safe struct in C++, Swift, or Kotlin. When you define a struct in your .nitro.ts spec, Nitro ensures that the types are strictly enforced across the JS/Native boundary. For example, a string in TypeScript will always be a string in native code, and fields will never be null or undefined unless explicitly handled.

interface Person {
  name: string
  age: number
}

interface Nitro
  extends HybridObject<{ ios: 'swift' }> {
  getAuthor(): Person
}

To perform heavy or long-running tasks in parallel without blocking the JavaScript thread, you can make native functions asynchronous by returning a Promise<T>. This allows the JS thread to continue rendering and executing business logic while the native code runs on a separate thread.

Nitro provides platform-specific implementations of Promise<T> for Swift, Kotlin, and C++ to integrate with their respective concurrency models (async/await, coroutines, and thread pools).