rnn-codebase

by wix

Navigate and work with the react-native-navigation (RNN) codebase. Use when fixing bugs, adding features, tracing command flows, understanding options… npx skills add https://github.com/wix/react-native-navigation --skill rnn-codebase Download ZIPGitHub13.2k

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:

• Navigation.push() → Commands.ts → processing pipeline → NativeCommandsSender.ts

• TurboModule: RNNTurboModule (iOS) / NavigationTurboModule.kt (Android)

• iOS: RNNCommandsHandler → RNNViewControllerFactory → UIKit controllers

• Android: Navigator → LayoutFactory → View-based controllers (no Fragments)

Read ARCHITECTURE.md for the full overview.

Key Cross-Layer Mappings

Layout Types → Native Controllers

JS Layout Type iOS Controller Android Controller component RNNComponentViewController ComponentViewController stack RNNStackController (UINavigationController) StackController bottomTabs RNNBottomTabsController (UITabBarController) BottomTabsController sideMenu RNNSideMenuViewController (MMDrawerController) SideMenuController (DrawerLayout) topTabs RNNTopTabsViewController TopTabsController (ViewPager) splitView RNNSplitViewController N/A (iOS only) externalComponent RNNExternalViewController ExternalComponentViewController

Options → Presenters

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

iOS Controller iOS Presenter Android Presenter RNNComponentViewController RNNComponentPresenter ComponentPresenter RNNStackController RNNStackPresenter + TopBarPresenter StackPresenter RNNBottomTabsController RNNBottomTabsPresenter BottomTabsPresenter RNNSideMenuViewController RNNSideMenuPresenter SideMenuPresenter

Events (same names both platforms)

Event Trigger RNN.ComponentDidAppear Screen becomes visible RNN.ComponentDidDisappear Screen hidden RNN.NavigationButtonPressed TopBar button tap RNN.BottomTabSelected Tab changed RNN.ModalDismissed Modal dismissed RNN.ScreenPopped Screen popped from stack RNN.CommandCompleted Any command finished

Where to Find Things

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

Task JS File(s) iOS File(s) Android File(s) Command execution src/commands/Commands.ts ios/RNNCommandsHandler.mm react/NavigationTurboModule.kt Layout creation src/commands/LayoutTreeParser.ts ios/RNNViewControllerFactory.mm options/LayoutFactory.java Options processing src/commands/OptionsProcessor.ts ios/RNNNavigationOptions.mm options/Options.java Options application — ios/*Presenter.mm viewcontrollers/*Presenter.java TopBar src/interfaces/Options.ts (TopBarOptions) ios/TopBarPresenter.mm, ios/RNNUIBarButtonItem.mm views/stack/topbar/ Bottom tabs src/interfaces/Options.ts (BottomTabsOptions) ios/RNNBottomTabsPresenter.mm viewcontrollers/bottomtabs/ Modals src/commands/Commands.ts ios/RNNModalManager.mm viewcontrollers/modal/ModalStack.java Overlays src/commands/Commands.ts ios/RNNOverlayManager.mm viewcontrollers/overlay/OverlayManager.kt Animations src/interfaces/Options.ts (AnimationOptions) ios/ScreenAnimationController.mm viewcontrollers/stack/StackAnimator.kt React view rendering — ios/RNNReactView.mm react/ReactView.java Events to JS src/adapters/NativeEventsReceiver.ts ios/RNNEventEmitter.mm react/events/EventEmitter.java Component registration src/components/ComponentRegistry.ts — — Deep linking (URL → screen) src/linking/ (LinkingHandler, URLParser, RouteMatcher, DeferredLinkQueue, ModalLayoutBuilder) ios/RNNAppDelegate.mm (dispatchDeepLinkURL:, cold-start queue, RCTContentDidAppearNotification) NavigationActivity.onNewIntent → ReactGateway

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:

• Default options (from Navigation.setDefaultOptions()) — lowest priority

• Static options (from component class or Navigation.registerComponent)

• Options passed in the layout call (e.g. push, setRoot)

• 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

• Deep links are processed only after the first setRoot() resolves; pre-bridge URLs on iOS are queued natively in RNNAppDelegate and flushed on RCTContentDidAppearNotification (bridgeless mode — RCTJavaScriptDidLoadNotification does NOT fire)

• ModalLayoutBuilder strips React-reserved keys (ref, key) from URL query params before they reach passProps, to avoid React 19 ref-validation crashes