react-native-nitro-modules is a core library that contains highly efficient statically compiled JS to C++ bindings.

It uses JSI to generate C++ templates that can bridge virtually any JS type to a C++ type with minimal overhead.

Installation

Inside an app

Install react-native-nitro-modules as a dependency in your react-native app:

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

Inside a nitro module library

If you are building a nitro module yourself, add react-native-nitro-modules as a peerDependency into your library's package.json:

1{
2  ...
3  "peerDependencies": {
4    ...
5    "react-native-nitro-modules": "*"
6  },
7}

Then install react-native-nitro-modules as a normal dependency in your library's example/ app as seen above.

Usage

react-native-nitro-modules can either be used with-, or without nitrogen, or mixed (some objects are automatically generated, some manually).

With Nitrogen

When using Nitrogen, all the bindings are automatically generated. You only need to implement C++, Swift or Kotlin interfaces inside your codebase.

Without Nitrogen

All C++ bindings are bridged to JS using "Hybrid Objects".

A Hybrid Object can have both methods and properties (get and set). Create a C++ Hybrid Object by inheriting from HybridObject:

1#include <NitroModules/HybridObject.hpp>
2
3using namespace margelo::nitro;
4
5class MyHybridObject: public HybridObject {
6public:
7  explicit MyHybridObject(): HybridObject(TAG) {}
8
9public:
10  // Property (get)
11  double getNumber() { return 13; }
12  // Property (set)
13  void setNumber(double value) { }
14  // Method
15  double add(double left, double right) { return left + right; }
16
17public:
18  void loadHybridMethods() override {
19    // Call base method to make sure we properly inherit `toString()` and `equals()`
20    HybridObject::loadHybridMethods();
21    // Register all methods that need to be exposed to JS
22    registerHybrids(this, [](Prototype& prototype) {
23      prototype.registerHybridGetter("number", &MyHybridObject::getNumber);
24      prototype.registerHybridSetter("number", &MyHybridObject::setNumber);
25      prototype.registerHybridMethod("add", &MyHybridObject::add);
26    });
27  }
28
29private:
30  static constexpr auto TAG = "MyHybrid";
31};

The MyHybridObject can then be registered in the HybridObjectRegistry at app startup:

1#include <NitroModules/HybridObjectRegistry.hpp>
2
3// Call this at app startup to register the HybridObjects
4void load() {
5  HybridObjectRegistry::registerHybridObjectConstructor(
6    "MyHybrid",
7    []() -> std::shared_ptr<HybridObject> {
8      return std::make_shared<MyHybridObject>();
9    }
10  );
11}

Inside your MyHybridObject, you can use standard C++ types which will automatically be converted to JS using Nitro's JSIConverter<T> interface.

The following C++ / JS types are supported out of the box:

JS Type	C++ Type	Swift Type	Kotlin Type
number	double / int / float	Double	Double
boolean	bool	Bool	Boolean
string	std::string	String	String
bigint	int64_t / uint64_t	Int64	Long
T[]	std::vector<T>	[T]	Array<T> / PrimitiveArray
[A, B, C, ...]	std::tuple<A, B, C, ...>	(A, B, C) 🟡  (#38)	❌
A | B | C | ...	std::variant<A, B, C, ...>	Variant_A_B_C	Variant_A_B_C
Record<string, T>	std::unordered_map<std::string, T>	Dictionary<String, T>	Map<std::string, T>
T?	std::optional<T>	T?	T?
(T...) => void	std::function<void (T...)>	@escaping (T...) -> Void	(T...) -> Unit
(T...) => R	std::function<std::shared_ptr<Promise<R>> (T...)>	(T...) -> Promise<T>	(T...) -> Promise<T>
Sync<(T...) => R>	std::function<R (T...)>	@escaping (T...) -> R	(T...) -> R
Error	std::exception_ptr	Error	Throwable
Promise<T>	std::shared_ptr<Promise<T>>	Promise<T>	Promise<T>
{ ... }	std::shared_ptr<AnyMap>	AnyMap	AnyMap
ArrayBuffer	std::shared_ptr<ArrayBuffer>	ArrayBuffer	ArrayBuffer
Date	std::chrono::system_clock::time_point	Date	java.time.Instant
..any HybridObject	std::shared_ptr<HybridObject>	HybridObject	HybridObject
..any interface	T	T	T
..any enum	T	T	T
..any union	T	T	T

Since the JSIConverter<T> is just a template, you can extend it with any other custom types by overloading the interface.

For example, to add support for an enum, overload JSIConverter<MyEnum>:

1#include <NitroModules/JSIConverter.hpp>
2
3enum class MyEnum {
4  FIRST = 0,
5  SECOND = 1
6};
7
8namespace margelo::nitro {
9  template <>
10  struct JSIConverter<MyEnum> {
11    static inline MyEnum fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
12      int intValue = JSIConverter<int>::fromJSI(runtime, arg);
13      return static_cast<MyEnum>(intValue);
14    }
15    static inline jsi::Value toJSI(jsi::Runtime& runtime, MyEnum arg) {
16      int intValue = static_cast<int>(arg);
17      return JSIConverter<int>::toJSI(runtime, intValue);
18    }
19  };
20}

Once the JSIConverter<T> for MyEnum is defined, you can use the type MyEnum in C++ methods, getters and setters of HybridObjects.

And on the JS side, you can simply treat the returned number (int) as a MyEnum:

1enum MyEnum {
2  FIRST = 0,
3  SECOND = 1
4}
5const value = myHybridObject.getEnumValue() // <-- typed as `MyEnum` instead of `number`

Make sure to always include the header that defines the JSIConverter<MyEnum> overload inside the MyHybridObject file, as this is where the JSIConverter<T> overloads are accessed from.

Nitrogen can automatically generate such JSIConverter<T> extensions for enums, TypeScript unions, and even structs/objects - so it is generally recommended to use nitrogen.