huytdps13400/react-native-ssl-manager / .agents/skills/build-nitro-modules
build-nitro-modules
VerifiedBuilds and designs React Native Nitro Modules with Nitrogen, HybridObject TypeScript specs, generated native implementations, zero-copy and native-state APIs, Swift/Kotlin/C++ bindings, example apps, and testing. Use when creating a Nitro Module, adding or reviewing HybridObjects, designing Nitro-specific public APIs, implementing native functionality, or setting up the nitrogen codegen pipeline. Pair with api-design for general library API shape.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 37.3 KB |
| references/example-android-config.md | markdown | 7.3 KB |
| references/example-app-setup.md | markdown | 5.7 KB |
| references/example-metro-install.md | markdown | 6.4 KB |
| references/native-implement-cpp.md | markdown | 11.6 KB |
| references/native-implement-kotlin.md | markdown | 20.5 KB |
| references/native-implement-swift.md | markdown | 21.5 KB |
| references/native-nitrogen-codegen.md | markdown | 6.6 KB |
| references/release-it-publishing.md | markdown | 4.1 KB |
| references/repo-structure-and-workflow.md | markdown | 6.3 KB |
| references/setup-monorepo-init.md | markdown | 5.2 KB |
| references/spec-hybrid-object.md | markdown | 27.0 KB |
| references/spec-nitro-json.md | markdown | 5.9 KB |
| references/spec-package-publish.md | markdown | 7.7 KB |
| references/vision-camera-golden-standard.md | markdown | 10.0 KB |
references/spec-nitro-json.md
View on GitHub---
title: Configuring nitro.json for Autolinking
impact: CRITICAL
tags: nitro-json, autolinking, cxxNamespace, iosModuleName, androidNamespace, androidCxxLibName, configuration
---
# Skill: Configuring nitro.json for Autolinking
Covers Step 5: updating `nitro.json` with all required fields for Nitrogen codegen and autolinking.
## Quick Config
```json
{
"$schema": "https://nitro.margelo.com/nitro.schema.json",
"cxxNamespace": ["math"],
"ios": {
"iosModuleName": "NitroMath"
},
"android": {
"androidNamespace": ["math"],
"androidCxxLibName": "NitroMath"
},
"autolinking": {
"Math": {
"ios": {
"language": "swift",
"implementationClassName": "HybridMath"
},
"android": {
"language": "kotlin",
"implementationClassName": "HybridMath"
}
}
}
}
```
## When to Use
- After writing the `*.nitro.ts` spec, before running `bunx nitrogen`
- When adding new HybridObjects to an existing module
- When autolinking fails at runtime
## Prerequisites
- `nitro.json` exists in the package root (created by `nitrogen init`)
- `*.nitro.ts` spec file written with interface name known
## Step-by-Step
### 1. Set `cxxNamespace`
Defines the C++ namespace for all generated code. Use a lowercase array:
```json
"cxxNamespace": ["math"]
// generates: namespace margelo::nitro::math { ... }
"cxxNamespace": ["math", "extra"]
// generates: namespace margelo::nitro::math::extra { ... }
```
### 2. Set iOS module name
Must match the CocoaPod's podspec name exactly:
```json
"ios": {
"iosModuleName": "NitroMath"
}
```
Check `NitroMath.podspec` at package root — the filename, `s.name`, and `ios.iosModuleName` should match.
### 3. Set Android configuration
```json
"android": {
"androidNamespace": ["math"],
"androidCxxLibName": "NitroMath"
}
```
- `androidNamespace`: Kotlin package suffix appended to `com.margelo.nitro`
- `["math"]` → package `com.margelo.nitro.math`
- `androidCxxLibName`: Name of the native C++ library loaded via JNI
- Must match the library name in `android/CMakeLists.txt`: `add_library(NitroMath SHARED ...)`
### 4. Configure `autolinking`
This is how Nitro knows which native class handles each HybridObject:
```json
"autolinking": {
"Math": {
"ios": {
"language": "swift",
"implementationClassName": "HybridMath"
},
"android": {
"language": "kotlin",
"implementationClassName": "HybridMath"
}
}
}
```
For C++ cross-platform (single implementation for iOS + Android):
```json
"autolinking": {
"Math": {
"all": {
"language": "c++",
"implementationClassName": "HybridMath"
}
}
}
```
Rules:
- The key (`"Math"`) must **exactly match** the string passed to `NitroModules.createHybridObject<Math>('Math')`
- Each entry requires `language` and `implementationClassName`
- Use `"all"` for a shared C++ implementation; use `"ios"` / `"android"` for platform-specific Swift/Kotlin
- The native classes must be **default-constructible** (no required constructor arguments)
- Only autolink objects JS creates directly, such as root factories, public utility singletons, or Hybrid Views. Objects returned from factory methods do not need autolinking entries.
- For objects that require constructor arguments, async setup, I/O, validation, or ownership of another object, expose a factory method instead of autolinking them directly.
### 5. Multiple HybridObjects
```json
"autolinking": {
"Math": {
"ios": {
"language": "swift",
"implementationClassName": "HybridMath"
},
"android": {
"language": "kotlin",
"implementationClassName": "HybridMath"
}
},
"Crypto": {
"ios": {
"language": "swift",
"implementationClassName": "HybridCrypto"
},
"android": {
"language": "kotlin",
"implementationClassName": "HybridCrypto"
}
}
}
```
### 6. Optional fields
```json
{
"ignorePaths": ["**/node_modules"],
"gitAttributesGeneratedFlag": true
}
```
- `ignorePaths`: Directories Nitrogen skips when scanning for `.nitro.ts` files
- `gitAttributesGeneratedFlag`: Marks generated files as `linguist-generated` on GitHub
## Code Examples
### C++ only (cross-platform) config
```json
{
"$schema": "https://nitro.margelo.com/nitro.schema.json",
"cxxNamespace": ["math"],
"ios": {
"iosModuleName": "NitroMath"
},
"android": {
"androidNamespace": ["math"],
"androidCxxLibName": "NitroMath"
},
"autolinking": {
"Math": {
"all": {
"language": "c++",
"implementationClassName": "HybridMath"
}
}
}
}
```
### Full config with all options
```json
{
"$schema": "https://nitro.margelo.com/nitro.schema.json",
"cxxNamespace": ["math"],
"ios": {
"iosModuleName": "NitroMath"
},
"android": {
"androidNamespace": ["math"],
"androidCxxLibName": "NitroMath"
},
"autolinking": {
"Math": {
"ios": {
"language": "swift",
"implementationClassName": "HybridMath"
},
"android": {
"language": "kotlin",
"implementationClassName": "HybridMath"
}
}
},
"ignorePaths": ["**/node_modules"],
"gitAttributesGeneratedFlag": true
}
```
## Common Pitfalls
- **Autolinking key mismatch** — `"Math"` in `nitro.json` must match `createHybridObject('Math')` exactly (case-sensitive)
- **`androidCxxLibName` mismatch** — Must match `add_library(<name> SHARED ...)` in `CMakeLists.txt`
- **`iosModuleName` mismatch** — Must match `s.name` in the `.podspec` file
- **Missing `$schema`** — Without the schema reference, some validators won't catch errors
- **Non-default-constructible class in autolinking** — Native classes registered via autolinking must have a no-argument constructor
## Related Skills
- [spec-hybrid-object.md](spec-hybrid-object.md) — Write the spec before configuring nitro.json
- [native-nitrogen-codegen.md](native-nitrogen-codegen.md) — Run nitrogen after configuring nitro.json
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |