Build Nitro Modules

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) that reads .nitro.ts spec files and generates native C++/Swift/Kotlin boilerplate. You then fill in the implementation. This is fundamentally different from old-style turbo modules.

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

Problem → Skill Mapping