Nitro Modules for React Native: JSI Native Bindings and Setup

Nitro's React Native Boundary Problem

Nitro Modules addresses the boundary between JavaScript application code and native implementations in React Native. The project describes its components as fast, type-safe native modules with statically compiled bindings to JSI. That boundary is relevant when an application needs native behavior, reusable platform code, or a module interface shared across several applications.

The project is aimed at React Native developers and authors of native-module libraries. Its supported implementation choices are C++, Swift, or Kotlin, depending on the platform. A module can therefore be written in pure C++ for cross-platform use, in Swift for iOS, or in Kotlin or Java for Android. The README specifically presents Nitro as a way to bridge custom C++ types with minimal overhead, rather than as a general-purpose JavaScript runtime optimization.

Nitro is not a replacement for React Native's application layer. It is a binding and module-generation layer for code that crosses into native territory. The repository also includes a separate `nitrogen` code generator for module authors. That division matters: using Nitro in an application and authoring a reusable Nitro package are related but different tasks, with different repositories, commands, and generated interfaces involved.

How Nitro's JSI Binding Flow Is Structured

The documented flow begins with a TypeScript interface. The interface extends `HybridObject` and declares the methods and types that JavaScript will use. In the README example, a `Math` interface declares an `add` method that accepts two numbers and returns a number.

An implementation then subclasses the generated specification. The C++ example defines `HybridMath` from `HybridMathSpec` and supplies the `add` method. Nitro uses the interface as the contract between the TypeScript-facing API and the native object. The README states that JavaScript and C++ type converters are statically generated ahead of time. That means the conversion layer is produced before runtime rather than assembled through dynamic lookups or a runtime parser, according to the project description.

At runtime, application code creates the object through `NitroModules.createHybridObject<Math>('Math')`. The returned object exposes the declared TypeScript methods to JavaScript, while the native class supplies the behavior. This design keeps the JavaScript call site small and makes the native implementation replaceable across supported platforms when the generated specification matches.

The project also documents platform-specific integration. On iOS, Swift 5.9 can bridge directly to C++, avoiding an Objective-C message-send step. On Android, fbjni is used to bridge complex types to Kotlin or Java. These statements describe the intended architecture, but they do not establish that every module can be written once without platform-specific project configuration.

Installing Nitro Modules in a React Native Project

The README gives a short installation path for the runtime package. This command installs `react-native-nitro-modules` from npm. The following command runs CocoaPods from the `ios` directory, which is the iOS dependency installation step documented by the project.

npm i react-native-nitro-modules
cd ios && pod install

After installation, the README's usage example creates a hybrid object and calls its method. The import comes from `react-native-nitro-modules`, and the object name is `Math`.

import { NitroModules } from 'react-native-nitro-modules'

const math = NitroModules.createHybridObject<Math>('Math')
const result = math.add(5, 3)

The README does not provide a complete application bootstrap command for Android, nor does it document every environment variable, Gradle setting, Xcode setting, or version requirement needed to produce a native binary. Those details are outside the installation section. The repository root does show a separate development workflow using Bun, including `bun i`, `bun run build`, and a `bootstrap` script, but that workflow belongs to repository development rather than a documented consumer installation guide.

The package metadata identifies `[email protected]` as the repository package manager and defines a `postinstall` script that runs `bun run build`. That is evidence about the monorepo's own tooling, not a requirement for installing the published package with npm. Consumers should distinguish the published runtime package from the full source repository.

Cross-Platform Modules Versus Swift and Kotlin Choices

Nitro's main architectural choice is shared C++ for code that should work across platforms. The README says custom C++ types can be bridged to JavaScript with minimal overhead and that generated converters handle JavaScript to C++ conversion. This is attractive for module libraries whose behavior is portable and whose platform-specific parts are limited.

Swift is the documented iOS alternative. The project credits Swift 5.9 C++ interoperability with allowing Swift modules to bridge directly to C++. That changes the implementation boundary for teams that prefer Swift APIs while retaining C++ components. It does not mean a Swift module automatically becomes an Android module.

Android modules can use C++, Kotlin, or Java, with fbjni handling the bridge to Kotlin or Java. Again, the README describes support for different native authoring languages, not a promise that one source file can serve every platform. Each target still has its own compilation and packaging rules. A library that wants shared behavior may place portable logic in C++, expose platform-specific conveniences in Swift or Kotlin, and use `nitrogen` to generate the binding contract.

The repository description also associates Nitro with TurboModules, but the README focuses on Nitro's own JSI binding layer. It does not provide a migration guide, compatibility matrix, or instructions for moving an existing TurboModule into Nitro. That omission makes adoption evaluation more dependent on the separate Nitro documentation.

Nitrogen, Generated Specifications, and Authoring Costs

`nitrogen` is the optional code generator for authors of Nitro module libraries. The distinction matters because the runtime package can be consumed by application code, while library authors also need generated specifications and platform integration. The repository includes `packages/nitrogen`, and the root build script runs `bun nitrogen build` along with builds for the core and test packages.

The declaration model makes generation central. A TypeScript specification describes the methods and types exposed to JavaScript, while native code implements the corresponding generated specification. This can reduce handwritten adapter code, but it also creates a build-time contract that must stay synchronized with every platform implementation. A mismatch in a declaration, generated header, or native registration name can prevent the object from being created correctly.

The README does not document generated-file locations, regeneration commands for an individual module, rollback instructions, or a compatibility policy for generated code. It also does not state whether a package author can safely update the generator independently of the runtime. Those are concrete points to check in `packages/nitrogen/README.md` and the Nitro documentation before committing a library to this workflow.

The repository has separate `typecheck`, `lint`, and language-specific formatting scripts. Those commands indicate that the project includes validation and maintenance surfaces for C++, Swift, Kotlin, and TypeScript. They do not prove that a consumer's native build will pass on every operating system or toolchain.

Limits of Nitro Modules and a Bridge-Based Alternative

The clearest limitation is the native build requirement. Nitro's value comes from compiling native code and generating bindings, so it adds more moving parts than a JavaScript-only module or a standard bridge-based integration. The README documents an npm install and `pod install`, but it does not document a complete Android setup or every compiler and runtime prerequisite. Teams without native iOS or Android build capacity may find that inconvenient.

There is also a distinction between portability and implementation simplicity. C++ can centralize portable logic, but platform views, platform SDK behavior, and language-specific APIs can still require separate code. Swift 5.9 interoperability reduces an Objective-C hop on iOS, while fbjni provides a Kotlin or Java bridge on Android. Neither statement removes the need to configure and compile each target.

A conventional React Native native-module path is another possible approach, but the README does not document its integration details. The approach differs at the boundary: it relies on platform bridge conventions and their adapters instead of Nitro's statically generated JSI converters and `HybridObject` contract. Nitro is the more specialized choice when direct JSI access, generated type converters, or shared C++ is central. The bridge-based route may be simpler when a small platform-specific module does not need those features. The README does not document a detailed migration path, so existing-module compatibility remains unverified.

Nitro Release and Maintenance Signals

The repository is not archived, and its last push was on 2026-10-16. The release list includes `v0.37.1` dated 2026-08-27, `v0.37.0` dated 2026-08-20, and `v0.37.0-beta.1` dated 2026-08-20. These are concrete release and repository signals, but they do not by themselves describe compatibility guarantees or production suitability.

The repository contains `CONTRIBUTING.md`, a contributing guide, multiple package workspaces, language-specific formatting scripts, and separate build targets. That layout indicates ongoing development work across the runtime, generator, test modules, examples, and documentation. The repository files do not specify a support window for older versions, a changelog policy, migration guarantees for breaking changes, or the exact upgrade procedure between releases.

The project uses the MIT License. That is the license identifier stated by the repository and should be checked in the project's `LICENSE` file for the actual terms applicable to the code being distributed. The README does not provide legal interpretation of the license, dependency licenses, native SDK terms, or app-store obligations. Review those separate obligations before shipping a Nitro-based application or module.

Editorial conclusion

Nitro Modules is suitable for React Native teams that want shared C++ code or direct Swift and Kotlin integration through statically generated JSI bindings. It is a poor fit for projects that need a JavaScript-only workflow or expect one implementation to remove all platform-specific native build work. Before adoption, verify the target iOS and Android toolchains, the generated interface for the required types, and the package's current 0.37.1 documentation and release state.

Frequently asked questions

Official sources

1. License: MIT
2. margelo/nitro on GitHub
3. Project website
4. README
5. Releases