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.

Generated files under nitrogen/generated/ are outputs. Change the .nitro.ts spec or native implementation source, then re-run nitrogen instead of manually editing generated files. These files can be committed to git, and many Nitro libraries do commit them, but the repo policy can choose otherwise. They must be included in the npm package so consumers can build the native library.

Pair With API Design

Use api-design first when shaping the public TypeScript, JavaScript, React, or React Native API. This skill adds the Nitro-specific constraints: HybridObject state, generated specs, native resource ownership, zero-copy data, threading, platform implementation, codegen, and real-device validation.

Let api-design own general public API rules and API freshness checks. In this skill, only add Nitro-specific freshness checks for mobile toolchain and generated-template decisions: verify current Nitro, React Native, Gradle, Xcode, Swift, Kotlin, NDK, and package-tooling docs/source before choosing versions, config fields, or native implementation details.

If the user is building a JS-only React or React Native library, do not apply this skill unless Nitro, HybridObjects, native modules, codegen, C++/Swift/Kotlin bindings, or react-native-nitro-modules are part of the task.

Pair with swift when implementing or reviewing Swift-backed HybridObjects, AVFoundation/session code, DispatchQueue usage, Swift concurrency, or thread-affine Swift state. Pair with kotlin when implementing or reviewing Kotlin-backed HybridObjects, Android threading, coroutines, Kotlin nullability, sealed result models, or Android service access. Pair with cpp when implementing or reviewing C++-backed HybridObjects, shared native engines, CMake, RAII ownership, or generated C++ spec bindings.

Repo and Release References

Load [repo-structure-and-workflow.md][repo-structure-and-workflow] only when creating a repo, reorganizing layout, adding examples/docs/CI, or changing workflow policy.

Load [release-it-publishing.md][release-it-publishing] only when setting up or reviewing bun release / release-it.

Nitro API Design Rules

• Prefer Nitro Modules over TurboModules or handwritten JSI for native module work. Nitro is usually faster and safer because it avoids many raw JSI lifetime, threading, and runtime-destruction hazards. Use raw JSI only when Nitro's Raw JSI Methods are required.
• Keep the root HybridObject default-constructible for autolinking. Create argument-dependent objects through factory methods.
• Use HybridObjects for native state: native resources, prewarmed engines, files, images, databases, sensor sessions, streams, and other stateful objects.
• If native setup is required, make the factory method async and resolve with a ready HybridObject, such as createCameraSession(...): Promise<CameraSession>.
• One JS-facing HybridObject spec can have multiple native concrete classes implementing the generated spec. Use this to hide backend strategies behind one TypeScript type, for example CameraVideoOutput backed by either a movie-file output or a video-data-output plus asset writer. Factories choose the native implementation and return the shared spec type.
• Use a product/domain noun for the exported JS factory object, not the generated spec type name. For example, export VisionCamera = createHybridObject<CameraFactory>('CameraFactory') or Images = createHybridObject<ImageFactory>('ImageFactory'). This avoids collisions with CameraFactory/ImageFactory types without mechanically lowercasing them or adding Hybrid prefixes.
• Keep each HybridObject scoped to one purpose or lifecycle.
• Do not choose HybridObject boundaries only by domain noun. A one-shot command, an app-owned live session, a native view, and a long-lived engine are different contracts even when they belong to the same feature area.
• Split returned HybridObjects by stable semantic capability when their options, results, lifecycle, or future platform support differ. For example, a root DataScannerFactory can expose createBarcodeScanner() and createTextScanner() instead of one broad scanner whose text fields are nullable because Android currently supports only barcodes.
• It is valid for a factory to report isTextScannerAvailable: false or reject createTextScanner() on platforms that do not support that capability today. Future platform support should fill in the existing capability and flip availability to true, not require redesigning a fat HybridObject.
• Platform-specific capabilities can still be first-class HybridObjects when the concept is stable. For example, an iOS-only CameraObjectOutput can extend a shared CameraOutput, be marked @platform iOS, and reject at createObjectOutput(...) on Android instead of adding object-scanning nullable fields to every output.
• Use factory methods to separate workflows and make returned HybridObjects stronger. If createLiveScanner() returns a live scanner session, baseline session operations that the implementation controls should be guaranteed by that type. Backends that cannot provide the live workflow should fail creation or return a narrower object, not force the live object to expose dead methods, nullable baseline properties, or repeated can* checks.
• Return configured handles to avoid stale state. If configure(...) binds a device, output, stream, or native graph, return a new HybridObject handle for commands that only make sense for that configured resource. For example, a CameraSession.configure(...) method should return CameraController handles for setZoom(...) and focusTo(...) instead of putting those methods on CameraSession with implicit "current device" state.
• Reconfiguration should replace or invalidate handles whose native target changed. Do not keep commands on a broad parent HybridObject when the command target depends on the last successful configuration.
• For native negotiation, model requested intent separately from resolved state. Use ranked constraints or preferences as input, then return or emit a resolved config HybridObject/struct that describes what the session actually selected. Provide an explicit resolver method when callers need to preview the result without creating or starting the native session.
• Use capability fields for workflow discovery, optional preferences, and genuinely variable support. Do not use capabilities to paper over an oversized HybridObject whose methods are unsupported during normal use on a supported backend.
• Treat HybridObjects as primary API objects. Each primary HybridObject gets its own .nitro.ts file.
• Keep an inheritance family in one .nitro.ts file only when the file is named after the base HybridObject and child HybridObjects add few or no members, such as ScannedCode, ScannedBarcode, and ScannedQRCode in ScannedCode.nitro.ts.
• Put named codegen types in their own .ts files: string-literal unions/enums, structs/interfaces, option objects, event objects, callback option structs, and helper types. Nitro needs names for generated native structs and enum-like values. Import them into .nitro.ts specs and re-export public types from src/index.ts.
• Inline simple function callbacks in method signatures, for example addErrorListener(listener: (error: Error) => void): ListenerSubscription. Do not create one-off aliases such as ScannerErrorListener unless the function type is reused as a public concept across multiple APIs.
• Group multiple helper types in one file only when they form one tightly coupled logical construct, such as DynamicRange plus the exact literal unions that define it.
• Use HybridObject inheritance for shared native state plus specialized result shapes. Put shared properties such as IDs, bounds, raw values, formats, and value types on the base object instead of repeating them on every subtype.
• Use HybridObject inheritance for heterogeneous native result families. Example: ScannedItem owns common state and methods, while ScannedBarcode, ScannedQRCode, and ScannedFace extend it with specialized properties. APIs can return ScannedItem[]; JS narrows by a discriminator property, and native code can accept the generated base spec when it only needs common behavior.
• Do not model state families as one Nitro struct or HybridObject with every subtype field nullable. Use HybridObject inheritance, discriminated unions, or platform protocol/interface conformance so relationships such as barcode plus barcodeType are compile-time safe.
• Treat public Nitro HybridObjects as the imperative API. Export the generated Nitro API 1:1 when it is intended for users; do not add JS wrappers that pre-parse values, translate strings/enums, reshape options, inject hidden defaults, or call a different internal method shape than the .nitro.ts spec exposes.
• JS/TS layers are appropriate for intentionally higher-level APIs such as React hooks, React components, UI composition helpers, or when the HybridObject is only an internal implementation detail and does not match the user-facing mental model. In those cases, keep the boundary explicit: the wrapper is the public API and the Nitro object is internal.
• Autolink only public roots, factories, views, or global utilities that JS must construct directly. Other HybridObjects can be returned from factory methods and do not need their own nitro.json autolinking entries. Do not autolink every concrete native implementation of the same JS-facing spec.
• For native extension points, pair a JS-facing base HybridObject spec with a public native protocol/interface. The base spec lets JS pass the object through typed APIs; the native protocol/interface exposes platform-specific handles and behavior for first-party and third-party native code.
• When accepting an extensible HybridObject from JS, accept the generated base spec type, then cast to the native protocol/interface on the native side and throw a clear error if it does not conform. This keeps JS portable while native integrations stay strongly typed.
• Use Nitro structs for domain shapes, option groups, and same-type parameter clusters. Do not wrap unrelated hot-path values in a struct only to reduce argument count; Nitro eagerly converts structs, so unnecessary wrappers can be slower than explicit parameters.
• Remember that TypeScript optional fields become native optionals (T? / std::optional<T>) in generated Swift, Kotlin, and C++. Use optional Nitro fields only when absence is part of the intended public/native contract, not because a JS wrapper will translate them away.
• Prefer the Nitro method's generated structs to be the real public input shape. If defaults or resolved options are needed, model them explicitly in the spec/native implementation or provide a deliberately higher-level API above an internal HybridObject; do not add a casual JS normalization layer over a public HybridObject.
• Do not model high-volume native results, parsed payloads, images, buffers, or objects with many optional expensive fields as flat structs. Nitro structs are eagerly converted, so prefer stateful HybridObjects with lazy properties or methods for data the caller may never read.
• Decide explicitly whether each result should be a Nitro struct or HybridObject. A small immutable result with cheap scalar fields can be a struct. Use a HybridObject when the result owns native state, may expose lazy expensive data, needs zero-copy binary access, or is likely to grow behavior/methods.
• Use ArrayBuffer for small or truly zero-copy native data access. For large media, photos, scans, model outputs, or byte payloads, return a HybridObject and expose lazy methods such as toArrayBuffer(), toBase64(), or saveToTemporaryFile() instead of eagerly converting bytes into JS.
• Do not choose ArrayBuffer only because it is zero-copy. Use string for decoded text payloads and ArrayBuffer for raw bytes, binary payloads, media, or opaque data where byte-level access is the API contract.
• Keep raw native state behind HybridObjects when conversion cost matters. For example, a native barcode/photo/result object can expose rawValue, bounds, format, or byte data lazily instead of converting every field for every detection.
• For repeated events, prefer addOn...Listener(callback): ListenerSubscription and let each subscription own its cleanup. This avoids one caller replacing another caller's callback through shared object state.
• Listener subscriptions should be flat structs with a remove: () => void function field, not HybridObjects, unless they expose native state beyond cleanup. Call sites still use subscription.remove().
• Listener cleanup should stop future emissions. It does not need to cancel a callback already selected by an in-flight native event snapshot, so do not add locks or complex subscription state only for that guarantee.
• Do not lock listener add, remove, and callback invocation as a default implementation pattern. Prefer one owner thread/queue or immutable snapshots; add a lock only for a proven shared mutable race that cannot be removed by ownership.
• Use a setOn...(callback | undefined)-style API only for single hot-path callbacks owned by an object, where replacing or removing the callback is the natural operation. The set verb and docs must make the replacement semantics clear.
• If the native API exposes only one delegate/callback but the JS API is a repeated event, prefer multiplexing internally and exposing additive listeners unless doing so would be unsafe or too expensive for the hot path.
• Use Sync<(...) => ...> callbacks only for rare thread-bound hot paths that must synchronously execute on a specific JS runtime or worklet thread.
• For Nitro Views, expose the raw getHostComponent wrapper. Add React components or hooks only when they remove repeated setup code while staying layered over the same native objects and refs. Load [spec-hybrid-view.md][spec-hybrid-view] when creating or reviewing a Nitro View component.
• Follow api-design for naming, platform abstraction, sync/async boundaries, listener cleanup, errors, variants, TypeScript facades, and JSDoc contracts.

Nitro Native Implementation Rules