React Native Navigation Codebase

Architecture Overview

RNN has three layers that mirror each other:

JS/TS (src/)  →  TurboModule bridge  →  iOS native (ios/)
                                     →  Android native (android/)

A navigation command (e.g. push) flows:

1. Navigation.push() → Commands.ts → processing pipeline → NativeCommandsSender.ts
2. TurboModule: RNNTurboModule (iOS) / NavigationTurboModule.kt (Android)
3. iOS: RNNCommandsHandler → RNNViewControllerFactory → UIKit controllers
4. Android: Navigator → LayoutFactory → View-based controllers (no Fragments)

Read ARCHITECTURE.md for the full overview.

Key Cross-Layer Mappings

Layout Types → Native Controllers

Options → Presenters

Each controller type has a Presenter that applies options to views:

Events (same names both platforms)

Where to Find Things

By task: "I need to fix/change X"

By directory

• src/ — JS public API, commands, processing pipeline. See src/ARCHITECTURE.md
• ios/ — All Obj-C/C++ native code. See ios/ARCHITECTURE.md
• ios/TurboModules/ — New architecture entry points (RNNTurboModule, RNNTurboManager, RNNTurboCommandsHandler)
• android/src/main/java/com/reactnativenavigation/ — All Java/Kotlin native code. See android/ARCHITECTURE.md
• playground/ — Demo app for development and E2E tests
• playground/src/screens/ — Test screens exercising every feature
• playground/e2e/ — Detox E2E tests

Options Resolution Order

Options are applied in ascending priority:

1. Default options (from Navigation.setDefaultOptions()) — lowest priority
2. Static options (from component class or Navigation.registerComponent)
3. Options passed in the layout call (e.g. push, setRoot)
4. mergeOptions() — runtime override, highest priority

JS Processing Pipeline (exact order)

API layout → OptionsCrawler.crawl() → LayoutProcessor.process()
  → LayoutTreeParser.parse() → LayoutTreeCrawler.crawl()
  → OptionsProcessor (colors, assets, custom) → NativeCommandsSender

iOS Patterns

• All controllers conform to RNNLayoutProtocol
• RNNBasePresenter subclasses apply options — applyOptionsOnInit:, applyOptions:, mergeOptions:resolvedOptions:
• Commands run on main thread (RCTExecuteOnMainQueue)
• React views: RNNReactView wraps RCTSurfaceHostingView (new arch)
• Overlays use separate UIWindow instances (RNNOverlayWindow)
• RNNReactComponentRegistry caches React component instances

Android Patterns

• View-based, NOT Fragment-based
• All commands dispatched via UiThread.post()
• ViewController<T extends ViewGroup> is the base — createView() is abstract
• ParentController extends ChildController extends ViewController
• Bottom tabs use AHBottomNavigation library
• Three root layouts in NavigationActivity: rootLayout, modalsLayout, overlaysLayout
• Tab attachment modes: Together, OnSwitchToTab, AfterInitialTab

Development Workflow

Playground app

• yarn start — Metro bundler
• yarn xcode — Open iOS project
• yarn studio — Open Android project
• yarn pod-install — Install iOS pods

Testing

• yarn test-js — Jest unit tests
• yarn test-unit-ios — iOS native unit tests (XCTest)
• yarn test-unit-android — Android native unit tests (JUnit + Robolectric)
• yarn test-e2e-ios-ci / yarn test-e2e-android-ci — Detox E2E tests

Building

• yarn prepare — Builds src/ → lib/ (ESM + types)
• Codegen config: rnnavigation in package.json

Common Gotchas

• iOS uses UIKit subclasses (UINavigationController, UITabBarController); Android uses custom View hierarchy
• splitView is iOS-only
• Side menu: iOS uses MMDrawerController (3rd party); Android uses DrawerLayout (native)
• Options that exist in JS types may not be implemented on both platforms — check the presenter
• passProps are stored in JS Store, not sent to native (cleared before bridge crossing)
• The lib/ folder is generated — never edit it, edit src/ instead