Build Nitro Modules

Overview

End-to-end skill for building a React Native Nitro Module: monorepo scaffolding via Nitrogen, TypeScript HybridObject spec authoring, native code generation, platform implementation (C++/Swift/Kotlin), example app wiring, and publish preparation.

Nitro Modules use a codegen pipeline (

nitrogen

.nitro.ts

NEVER modify any file inside

nitrogen/generated/

. These files are fully regenerated every time

npx nitrogen

runs — any manual edits will be silently overwritten. Always edit only the

.nitro.ts

spec file, then re-run nitrogen to regenerate.

Ask First — Before Doing Anything

First, determine what the user wants to do:

"Are you creating a new Nitro Module library from scratch, or adding a new HybridObject to an existing library?"

If creating a new library — ask all of these before any command:

1. Library name — What should the library be called? (e.g.

   react-native-math

   )
2. Monorepo with

   packages/

   folder — Should the library live in

   packages/<name>

   inside a monorepo? (Strongly recommended — default: yes)
3. Example app — Should an example app be created to test the module? (Recommended — default: yes)
4. Native languages — Which platforms and languages?
   • iOS:

     swift

     (default) or

     cpp

   • Android:

     kotlin

     (default) or

     cpp

   • Cross-platform C++ only: both

     cpp

5. Module purpose — Briefly describe what the module does so the correct spec methods can be designed

Do not proceed past Step 1 of the build sequence until all five questions are answered.

If adding a HybridObject to an existing library — ask only:

1. HybridObject name — What should the new HybridObject be called? (e.g.

   Camera

   ,

   Crypto

   )
2. Native languages — iOS:

   swift

   or

   cpp

   ? Android:

   kotlin

   or

   cpp

   ?
3. Purpose — What does this HybridObject do?

Then skip directly to spec-hybrid-object.md (write the spec), spec-nitro-json.md (add autolinking entry), native-nitrogen-codegen.md (re-run nitrogen), and the relevant native implementation file. Skip all setup, monorepo, and example app steps.

Typical Build Sequence

# 1. Scaffold
npx nitrogen@latest init react-native-math

# 2. Run codegen (from package folder after writing spec + nitro.json)
cd packages/react-native-math && npx nitrogen

# 3. Create example app
npx @react-native-community/cli@latest init --skip-install MathExample

# 4. Install and test
cd example && bun add ../packages/react-native-math
bun add react-native-nitro-modules
bun example android
bun example ios

Full step-by-step references below.

When to Apply

Reference these guidelines when:

• Creating any new React Native native module using the Nitro framework
• Writing HybridObject TypeScript specs (

  *.nitro.ts

  files)
• Running Nitrogen codegen and implementing generated interfaces
• Setting up a monorepo example app for a Nitro library
• Configuring Android Gradle paths for a monorepo structure
• Debugging autolinking failures or missing generated files
• Preparing a Nitro module package for npm publishing

Priority-Ordered Guidelines

Quick Reference

Minimum HybridObject Spec (

src/specs/Math.nitro.ts

)

import { type HybridObject, NitroModules } from 'react-native-nitro-modules'

interface Math extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
  add(a: number, b: number): number
}

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

Minimum

nitro.json

{
  "$schema": "https://nitro.margelo.com/nitro.schema.json",
  "cxxNamespace": ["math"],
  "ios": { "iosModuleName": "ReactNativeMath" },
  "android": {
    "androidNamespace": ["math"],
    "androidCxxLibName": "ReactNativeMath"
  },
  "autolinking": {
    "Math": { "swift": "HybridMath", "kotlin": "HybridMath" }
  }
}

Root

package.json

Scripts

{
  "scripts": {
    "specs": "bun --cwd packages/react-native-math run specs",
    "example": "bun --cwd example"
  }
}

Run:

bun example android

bun example ios

bun specs

References

nitrogen init

*.nitro.ts

nitro.json

settings.gradle

build.gradle

package.json

files

Problem → Skill Mapping

nitrogen init

*.nitro.ts

nitro.json

override

watchFolders

metro.config.js

react-native

files

package.json