Skip to main content

Using Nitro in your app

While most libraries are built with Nitro and shipped over npm, you can also easily build a library with Nitro in your app - that's the "brownfield" way of doing things.

Installing Nitro​

First, you need to install the Nitro Modules core package from npm:

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

Creating a Hybrid Object​

After installing Nitro, you can start creating your Hybrid Objects - either with Nitrogen, or manually:

Nitrogen will ✨ automagically ✨ generate native specifications for each Hybrid Object based on a given TypeScript definition.

1. Installing Nitrogen​

First, install Nitrogen:

npm i nitro-codegen --save-dev
warning

Nitrogen is currently named nitro-codegen instead of nitrogen on npm.

Then, create your nitro.json configuration in your app's root directory:

{
  "$schema": "https://nitro.margelo.com/nitro.schema.json",
  "cxxNamespace": ["example"],
  "ios": {
    "iosModuleName": "NitroExample"
  },
  "android": {
    "androidNamespace": ["example"],
    "androidCxxLibName": "NitroExample"
  },
  "autolinking": {}
}

Note: Replace Example with your app's name.

2. Creating Nitro specs​

Now it's time to create your first spec. Let's create Math.nitro.ts:

Math.nitro.ts
interface Math extends HybridObject<{ ios: 'swift', android: 'kotlin' }> {
  readonly pi: number
  add(a: number, b: number): number
}

And now let's run Nitrogen:

npm run nitro-codegen
warning

Nitrogen is currently named nitro-codegen instead of nitrogen on npm.

This will generate the native Swift and Kotlin protocol "HybridMathSpec", as well as some helper classes for autolinking and bridging to C++.

3. Adding the generated sources to your project​

You now need to add the generated sources to your project - either by creating a sub-package that you will use in your app (e.g. in a monorepo), or by just manually adding the source files:

iOS​

On iOS, you just need to drag and drop the nitrogen/generated/ios and nitrogen/generated/shared folders into your Xcode project. That's it.

Android​

For Android, you need to add everything in nitrogen/generated/android and nitrogen/generated/shared to your build.gradle (Java/Kotlin source) and CMake (C++ sources) project.

Java/Kotlin sources (build.gradle)​

Add the Java/Kotlin sources to your Gradle project by including the generated autolinking gradle file. Simply add this to the top of your app/build.gradle:

apply from: '../nitrogen/generated/android/NitroExample+autolinking.gradle'
C++ sources (CMakeLists.txt)​

Add the C++ sources to your CMake project by including the generated autolinking CMake file. If you do not have a CMake setup yet, make sure to configure CMake through externalNativeBuild in build.gradle. Simply add this to your CMakeLists.txt:

include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroImage+autolinking.cmake)

4. Implement Hybrid Object Specs​

After adding the generated sources to your project, you can start implementing the spec in a class:

HybridMath.swift
class HybridMath : HybridMathSpec {
  public var hybridContext = margelo.nitro.HybridContext()
  public var memorySize: Int {
    return getSizeOf(self)
  }

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

5. Registering the Hybrid Objects​

Nitro needs to be able to initialize an instance of your Hybrid Object - so we need to tell it how to do that. In your nitro.json, register HybridMath in the "autolinking" section:

{
  ...
  "autolinking": {
    "Math": {
      "swift": "HybridMath",
      "kotlin": "HybridMath"
    }
  }
}
warning
  • Make sure HybridMath is default-constructible. That is, it has a public initializer that takes no arguments.
  • Make sure the Java/Kotlin class HybridMath is inside the package/namespace com.margelo.nitro.$$androidNamespace$$ (as configured in nitro.json).
  • Make sure the Java/Kotlin class HybridMath is annotated with @DoNotStrip to avoid it from being compiled out in production builds.

For more information, see the Nitrogen documentation.

Using your Hybrid Objects​

And finally, to initialize HybridMath from JS you just need to call createHybridObject:

export const MathModule = NitroModules.createHybridObject<Math>("Math")
const result = MathModule.add(5, 7)
note

If this call failed, you might have forgotten to register your Hybrid Object's constructor in the HybridObjectRegistry.