How mrousavy/nitro works
Project type and purpose
• This is an open-source, full-stack monorepo for building “Nitro Modules”—high-performance, typesafe native modules for React Native—consisting of two core parts:
• react-native-nitro-modules: a C++/JSI runtime library that powers modules at runtime
• nitrogen: a Node/TypeScript-based CLI code generator that turns a high-level spec into platform-specific glue code
• It also includes example modules (react-native-nitro-image), a template for new modules, documentation (Docusaurus), and CI/CD workflows.
High-level file-structure analysis
• Top level
• config, scripts, .github/workflows → linting, formatting, CI/CD
• docs → Docusaurus site for end-user and contributor docs
• example → a React Native app showing how to consume a generated module
• packages
– nitrogen → code generator (TS, syntax trees, autolinking, platform specs)
– react-native-nitro-modules → core C++ library + TypeScript binding APIs + native platform integration
– react-native-nitro-image → sample module built with nitrogen, showing how to write specs and native implementations
– template → starter boilerplate for new Nitro modules
• Each package has its own src, native code (cpp, android, ios), build scripts (Gradle, CMake, Podspec), tests, and TS configs.
Key insights from README
• End-users write a TypeScript interface (“spec”) describing their API
• nitrogen generates ahead-of-time type converters, hybrid object “spec” classes, and autolinking scripts for iOS/Android
• Native authors implement C++/Swift/Kotlin overrides of the generated Spec classes
• JS consumers call NitroModules.createHybridObject<Spec>(name) to get a fully typesafe object whose methods are bridged via JSI to native code
Main components
a. Developer workstation (VS Code/CLI)
b. nitrogen CLI (Node.js/TypeScript)
c. Spec definitions (.nitro.ts files)
d. Generated output
• Platform code:
• iOS: Swift bridge files, C++ spec bindings, CocoaPods/Ruby autolinking
• Android: C++, Kotlin/Java spec bindings, CMake/Gradle fragments
• Shared C++ types (cpp headers)
e. Core runtime: react-native-nitro-modules
• JSI binding layer (C++)
• JS API (TypeScript wrapper, NitroModules.ts)
• Native core (C++ code, fbjni for Android, Swift↔C++ interop for iOS)
f. React Native runtime
• Metro bundler packages JS + generated TypeScript glue
• JavaScriptCore or Hermes with JSI interface
g. Example module: react-native-nitro-image
• Shows end-to-end flow: spec → codegen → native → JS consumption
h. CI/CD pipelines (.github/workflows) & documentation site (docs)
Relationships and interactions
• Developer runs nitrogen init / nitrogen generate on spec files
→ nitrogen reads spec definitions → emits platform-specific source and build fragments
→ those files are checked into a module package (template or example)
• Building the RN app
→ Gradle/CMake builds Android native library → produces a .so with JSI exports
→ Xcode/CocoaPods builds iOS framework with JSI symbols
• Running the RN app
→ Metro bundles JS+TS glue → at runtime, JS calls NitroModules.createHybridObject
→ JSI layer routes calls through the native runtime (C++), invoking the user’s HybridSpec implementation
→ Data flows back via statically generated converters (no dynamic reflection)
Architectural patterns & design principles
• Monorepo with well-scoped packages (Generator, Runtime, Examples, Templates)
• Code-generation pipeline: high-level specs → static binding code → zero-overhead interop
• Hybrid object pattern: abstract Spec base classes in C++/Swift/Kotlin that the author extends
• JSI bridging: direct C++ ↔ JavaScriptCore/Hermes communication for minimal overhead
• Autolinking: generated platform integration scripts (Podspec, CMake, Gradle) for frictionless installs