build-nitro-modules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Nitro Modules

构建 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.

一套构建 React Native Nitro Module 的端到端指南：通过 Nitrogen 搭建 monorepo 项目框架、编写 TypeScript HybridObject 规范、生成原生代码、实现多平台功能（C++/Swift/Kotlin）、配置示例应用，以及准备发布。

Nitro Modules 使用代码生成流水线（

nitrogen

）读取

.nitro.ts

规范文件，生成原生 C++/Swift/Kotlin 模板代码。开发者只需填充具体实现逻辑即可。这与传统的 turbo modules 有着本质区别。

**请勿修改
nitrogen/generated/
目录下的任何文件。**每次运行
npx nitrogen
时，这些文件都会被完全重新生成——手动修改的内容会被静默覆盖。请始终只编辑
.nitro.ts
规范文件，然后重新运行 nitrogen 以重新生成代码。

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?"

首先，明确用户的需求：

"你是要从零开始创建一个新的 Nitro Module 库，还是要向现有库中添加一个新的 HybridObject？"

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

如果是创建新库——执行任何命令前先确认以下所有问题：

Library name — What should the library be called? (e.g.
```
react-native-math
```
)
Monorepo with
packages/
folder — Should the library live in
```
packages/<name>
```
inside a monorepo? (Strongly recommended — default: yes)
Example app — Should an example app be created to test the module? (Recommended — default: yes)
Native languages — Which platforms and languages?
- iOS:
```
swift
```
  (default) or
```
cpp
```
- Android:
```
kotlin
```
  (default) or
```
cpp
```
- Cross-platform C++ only: both
```
cpp
```
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.

库名称——库的名称是什么？（例如：
```
react-native-math
```
）
带
packages/
目录的 monorepo——库是否要放在 monorepo 的
```
packages/<name>
```
目录下？（强烈推荐——默认：是）
示例应用——是否要创建示例应用来测试模块？（推荐——默认：是）
原生语言——支持哪些平台和语言？
- iOS：
```
swift
```
  （默认）或
```
cpp
```
- Android：
```
kotlin
```
  （默认）或
```
cpp
```
- 仅跨平台 C++：两者都选
```
cpp
```
模块用途——简要描述模块的功能，以便设计合适的规范方法

在完成所有5个问题的确认前，不要进入构建流程的第1步。

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

如果是向现有库添加 HybridObject——只需确认以下问题：

HybridObject name — What should the new HybridObject be called? (e.g.
```
Camera
```
,
```
Crypto
```
)
Native languages — iOS:
```
swift
```
or
```
cpp
```
? Android:
```
kotlin
```
or
```
cpp
```
?
Purpose — What does this HybridObject do?

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

HybridObject 名称——新的 HybridObject 叫什么？（例如：
```
Camera
```
、
```
Crypto
```
）
原生语言——iOS：
```
swift
```
还是
```
cpp
```
？Android：
```
kotlin
```
还是
```
cpp
```
？
用途——这个 HybridObject 的功能是什么？

然后直接跳转到 [spec-hybrid-object.md][spec-hybrid-object]（编写规范）、[spec-nitro-json.md][spec-nitro-json]（添加自动链接配置）、[native-nitrogen-codegen.md][native-nitrogen-codegen]（重新运行 nitrogen），以及对应的原生实现文件。跳过所有初始化、monorepo 和示例应用的设置步骤。

Typical Build Sequence

典型构建流程

bash

undefined

bash

undefined

1. Scaffold

1. 搭建项目框架

npx nitrogen@latest init react-native-math

2. Run codegen (from package folder after writing spec + nitro.json)

2. 运行代码生成（编写规范和 nitro.json 后，进入包目录执行）

cd packages/react-native-math && npx nitrogen

3. Create example app

3. 创建示例应用

npx @react-native-community/cli@latest init --skip-install MathExample

4. Install and test

4. 安装并测试

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.

cd example && bun add ../packages/react-native-math bun add react-native-nitro-modules bun example android bun example ios


详细分步参考如下。

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

在以下场景中可参考本指南：

使用 Nitro 框架创建任何新的 React Native 原生模块
编写 HybridObject TypeScript 规范（
```
*.nitro.ts
```
文件）
运行 Nitrogen 代码生成并实现生成的接口
为 Nitro 库搭建 monorepo 示例应用
为 monorepo 结构配置 Android Gradle 路径
调试自动链接失败或生成文件缺失的问题
为 npm 发布准备 Nitro 模块包

Priority-Ordered Guidelines

优先级指南

Priority	Category	Impact	Reference
1	Monorepo scaffold	CRITICAL	[setup-monorepo-init.md][setup-monorepo-init]
2	HybridObject spec	CRITICAL	[spec-hybrid-object.md][spec-hybrid-object]
3	nitro.json autolinking	CRITICAL	[spec-nitro-json.md][spec-nitro-json]
4	Nitrogen codegen	HIGH	[native-nitrogen-codegen.md][native-nitrogen-codegen]
5	C++ implementation	HIGH	[native-implement-cpp.md][native-implement-cpp]
6	Kotlin implementation	HIGH	[native-implement-kotlin.md][native-implement-kotlin]
7	Swift implementation	HIGH	[native-implement-swift.md][native-implement-swift]
8	Example app setup (if requested)	HIGH	[example-app-setup.md][example-app-setup]
9	Android Gradle paths (if example app)	HIGH	[example-android-config.md][example-android-config]
10	Metro + install + test (if example app)	HIGH	[example-metro-install.md][example-metro-install]
11	npm publish prep	MEDIUM	[spec-package-publish.md][spec-package-publish]

优先级	类别	影响程度	参考文档
1	Monorepo 项目搭建	关键	[setup-monorepo-init.md][setup-monorepo-init]
2	HybridObject 规范	关键	[spec-hybrid-object.md][spec-hybrid-object]
3	nitro.json 自动链接	关键	[spec-nitro-json.md][spec-nitro-json]
4	Nitrogen 代码生成	高	[native-nitrogen-codegen.md][native-nitrogen-codegen]
5	C++ 实现	高	[native-implement-cpp.md][native-implement-cpp]
6	Kotlin 实现	高	[native-implement-kotlin.md][native-implement-kotlin]
7	Swift 实现	高	[native-implement-swift.md][native-implement-swift]
8	示例应用设置（若需）	高	[example-app-setup.md][example-app-setup]
9	Android Gradle 路径（若有示例应用）	高	[example-android-config.md][example-android-config]
10	Metro + 安装 + 测试（若有示例应用）	高	[example-metro-install.md][example-metro-install]
11	npm 发布准备	中	[spec-package-publish.md][spec-package-publish]

Quick Reference

快速参考

Minimum HybridObject Spec (

src/specs/Math.nitro.ts

)

最简 HybridObject 规范（

src/specs/Math.nitro.ts

）

typescript

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 }

typescript

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

最简

nitro.json

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" }
  }
}

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

根目录

package.json

脚本

json

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

Run:

bun example android

bun example ios

bun specs

json

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

运行命令：

bun example android

bun example ios

bun specs

References

参考文档

File	Description
[setup-monorepo-init.md][setup-monorepo-init]	Monorepo workspace structure and `nitrogen init` scaffold
[spec-hybrid-object.md][spec-hybrid-object]	Writing `*.nitro.ts` specs and exporting HybridObjects
[spec-nitro-json.md][spec-nitro-json]	`nitro.json` all fields, autolinking, namespace configuration
[native-nitrogen-codegen.md][native-nitrogen-codegen]	Running Nitrogen and verifying generated files
[native-implement-cpp.md][native-implement-cpp]	Implementing HybridObjects in C++
[native-implement-kotlin.md][native-implement-kotlin]	Implementing HybridObjects in Kotlin (Android)
[native-implement-swift.md][native-implement-swift]	Implementing HybridObjects in Swift (iOS)
[example-app-setup.md][example-app-setup]	RN CLI example app init, workspace wiring, version alignment
[example-android-config.md][example-android-config]	`settings.gradle` and `build.gradle` monorepo path fixes
[example-metro-install.md][example-metro-install]	Metro watchFolders, library install, App.tsx usage, test runs
[spec-package-publish.md][spec-package-publish]	`package.json` author, `files` field, npm publish readiness

文件	描述
[setup-monorepo-init.md][setup-monorepo-init]	Monorepo 工作区结构与 `nitrogen init` 项目搭建
[spec-hybrid-object.md][spec-hybrid-object]	编写 `*.nitro.ts` 规范并导出 HybridObjects
[spec-nitro-json.md][spec-nitro-json]	`nitro.json` 所有字段、自动链接、命名空间配置
[native-nitrogen-codegen.md][native-nitrogen-codegen]	运行 Nitrogen 并验证生成文件
[native-implement-cpp.md][native-implement-cpp]	使用 C++ 实现 HybridObjects
[native-implement-kotlin.md][native-implement-kotlin]	使用 Kotlin 实现 HybridObjects（Android）
[native-implement-swift.md][native-implement-swift]	使用 Swift 实现 HybridObjects（iOS）
[example-app-setup.md][example-app-setup]	RN CLI 示例应用初始化、工作区配置、版本对齐
[example-android-config.md][example-android-config]	`settings.gradle` 和 `build.gradle` monorepo 路径修复
[example-metro-install.md][example-metro-install]	Metro watchFolders、库安装、App.tsx 使用、测试运行
[spec-package-publish.md][spec-package-publish]	`package.json` 作者信息、 `files` 字段、npm 发布准备

Problem → Skill Mapping

问题对应指南

Problem	Reference	Action
Don't know where to start	setup-monorepo-init.md	Scaffold with `nitrogen init`
Spec file syntax error	spec-hybrid-object.md	Fix `*.nitro.ts` interface
Autolinking not working	spec-nitro-json.md	Check `nitro.json` autolinking block
Nitrogen generates no files	native-nitrogen-codegen.md	Verify spec file extension and run command from right dir
C++ types unclear	native-implement-cpp.md	Follow type reference links to canonical examples
Kotlin compilation error	native-implement-kotlin.md	Check annotations and `override` modifiers
Swift compilation error	native-implement-swift.md	Check class inheritance and property signatures
Example app won't build (Android)	example-android-config.md	Fix Gradle monorepo path configuration
Metro can't resolve library	example-metro-install.md	Add `watchFolders` to `metro.config.js`
Version mismatch between example and package	example-app-setup.md	Align `react-native` versions across workspaces
Package missing files on npm	spec-package-publish.md	Fix `files` field in `package.json`

问题	参考文档	操作
不知道从何处开始	setup-monorepo-init.md	使用 `nitrogen init` 搭建项目框架
规范文件语法错误	spec-hybrid-object.md	修复 `*.nitro.ts` 接口
自动链接不生效	spec-nitro-json.md	检查 `nitro.json` 中的自动链接配置块
Nitrogen 未生成任何文件	native-nitrogen-codegen.md	验证规范文件扩展名，并确保在正确目录下运行命令
C++ 类型不明确	native-implement-cpp.md	参考类型链接中的标准示例
Kotlin 编译错误	native-implement-kotlin.md	检查注解和 `override` 修饰符
Swift 编译错误	native-implement-swift.md	检查类继承关系和属性签名
示例应用构建失败（Android）	example-android-config.md	修复 Gradle monorepo 路径配置
Metro 无法解析库	example-metro-install.md	向 `metro.config.js` 添加 `watchFolders`
示例应用与包版本不匹配	example-app-setup.md	对齐工作区中的 `react-native` 版本
npm 上的包缺失文件	spec-package-publish.md	修复 `package.json` 中的 `files` 字段

build-nitro-modules

Original

Translation

Build Nitro Modules

构建 Nitro Modules

Overview

概述

Ask First — Before Doing Anything

操作前必问

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

如果是创建新库——执行任何命令前先确认以下所有问题：

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

如果是向现有库添加 HybridObject——只需确认以下问题：

Typical Build Sequence

典型构建流程

1. Scaffold

1. 搭建项目框架

2. Run codegen (from package folder after writing spec + nitro.json)

2. 运行代码生成（编写规范和 nitro.json 后，进入包目录执行）

3. Create example app

3. 创建示例应用

4. Install and test

4. 安装并测试

When to Apply

适用场景

Priority-Ordered Guidelines

优先级指南

Quick Reference

快速参考

Minimum HybridObject Spec (
`src/specs/Math.nitro.ts`
)

最简 HybridObject 规范（
`src/specs/Math.nitro.ts`
）

Minimum
`nitro.json`

最简
`nitro.json`

Root
`package.json`
Scripts

根目录
`package.json`
脚本

References

参考文档

Problem → Skill Mapping

问题对应指南

build-nitro-modules

Original

Translation

Build Nitro Modules

构建 Nitro Modules

Overview

概述

Ask First — Before Doing Anything

操作前必问

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

如果是创建新库——执行任何命令前先确认以下所有问题：

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

如果是向现有库添加 HybridObject——只需确认以下问题：

Typical Build Sequence

典型构建流程

1. Scaffold

1. 搭建项目框架

2. Run codegen (from package folder after writing spec + nitro.json)

2. 运行代码生成（编写规范和 nitro.json 后，进入包目录执行）

3. Create example app

3. 创建示例应用

4. Install and test

4. 安装并测试

When to Apply

适用场景

Priority-Ordered Guidelines

优先级指南

Quick Reference

快速参考

Minimum HybridObject Spec (src/specs/Math.nitro.ts)

最简 HybridObject 规范（src/specs/Math.nitro.ts）

Minimum nitro.json

最简 nitro.json

Root package.json Scripts

根目录 package.json 脚本

References

参考文档

Problem → Skill Mapping

问题对应指南

Minimum HybridObject Spec (
`src/specs/Math.nitro.ts`
)

最简 HybridObject 规范（
`src/specs/Math.nitro.ts`
）

Minimum
`nitro.json`

最简
`nitro.json`

Root
`package.json`
Scripts

根目录
`package.json`
脚本