build-nitro-modules

Builds React Native Nitro Modules with Nitrogen codegen, HybridObject specs, and Swift, Kotlin, or C++ implementations.

172|8|Updated Apr 13, 2026
One-click install
npx skills add https://github.com/margelo/react-native-skills --skill build-nitro-modules-margelo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: build-nitro-modules
Source: https://github.com/margelo/react-native-skills/tree/main/skills/build-nitro-modules
Command: npx skills add https://github.com/margelo/react-native-skills --skill build-nitro-modules-margelo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building a React Native native module with the Nitro framework involves many error-prone steps: scaffolding a monorepo, writing HybridObject TypeScript specs, running Nitrogen codegen, implementing generated specs in Swift, Kotlin, or C++, wiring an example app, and preparing the package for npm publishing. This Skill guides the entire workflow with Nitro-specific API design rules and platform implementation patterns. ## Core Features & Use Cases - End-to-end module scaffolding: Initialize a Nitro library with Nitrogen, configure nitro.json autolinking, and set up a monorepo with an example app for real-device testing. - HybridObject API design: Apply Nitro-specific rules for factories, native state ownership, zero-copy data, listener subscriptions, Promise-based async boundaries, and Hybrid View components. - Native implementation guidance: Implement generated specs correctly in Swift, Kotlin, or C++ with proper threading, Promise helpers, annotations, and file organization. - Use Case: You want to create a react-native-math library with a native Math HybridObject. The Skill walks you through nitrogen init, writing Math.nitro.ts, running codegen, implementing HybridMath in Swift and Kotlin, and running the example app on Android and iOS. ## Quick Start Ask the assistant to create a new Nitro Module library, then answer its questions about the library name, monorepo layout, example app, native languages, and module purpose.

Frequently Asked Questions about build-nitro-modules

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a React Native Nitro Module from scratch?

Run `bunx nitrogen@latest init <name>` to scaffold the library, write a `.nitro.ts` HybridObject spec, configure `nitro.json` autolinking, then run `bunx nitrogen` to generate native code. Implement the generated spec in Swift, Kotlin, or C++, and test with an example app created via the React Native CLI.

What is a HybridObject in Nitro Modules?

A HybridObject is a TypeScript spec extending `HybridObject` that Nitrogen compiles into native Swift, Kotlin, or C++ interfaces. It represents native state such as sessions, engines, or files, and is the primary API object for Nitro libraries, created through default-constructible factory objects for autolinking.

Should I use Nitro Modules or TurboModules for React Native?

Nitro Modules are generally preferred over TurboModules or handwritten JSI because they avoid raw JSI lifetime, threading, and runtime-destruction hazards while offering strong codegen typing. Use raw JSI only when Nitro's Raw JSI Methods are specifically required.

What are the minimum requirements for Nitro Modules?

Current Nitro documentation lists React Native 0.75+, Xcode 16.4+, Swift 5.9+, Android compileSdkVersion 34+, and NDK 27+. Nitro Views additionally require React Native 0.78+ and the New Architecture. Verify current docs before choosing versions.

Why does my Kotlin HybridObject crash in release builds?

Release crashes usually happen because the implementation class is missing the `@Keep` and `@DoNotStrip` annotations, allowing ProGuard or R8 to strip it. Add both annotations to every Kotlin HybridObject implementation class.

When should a Nitro method return a Promise instead of a synchronous value?

Keep methods synchronous only for quick, deterministic, local work like cheap object creation or cached metadata. Use `Promise<T>` when work is heavy, fallible over time, crosses threads, or wraps native async APIs, using `Promise.async` for coroutine/async work and `Promise.parallel` for queue-owned CPU work.