|
| 1 | +--- |
| 2 | +name: rnn-codebase |
| 3 | +description: Navigate and work with the react-native-navigation (RNN) codebase. Use when fixing bugs, adding features, tracing command flows, understanding options resolution, or working across JS/iOS/Android layers in this repo. |
| 4 | +--- |
| 5 | + |
| 6 | +# React Native Navigation Codebase |
| 7 | + |
| 8 | +## Architecture Overview |
| 9 | + |
| 10 | +RNN has three layers that mirror each other: |
| 11 | + |
| 12 | +``` |
| 13 | +JS/TS (src/) → TurboModule bridge → iOS native (ios/) |
| 14 | + → Android native (android/) |
| 15 | +``` |
| 16 | + |
| 17 | +A navigation command (e.g. `push`) flows: |
| 18 | +1. `Navigation.push()` → `Commands.ts` → processing pipeline → `NativeCommandsSender.ts` |
| 19 | +2. TurboModule: `RNNTurboModule` (iOS) / `NavigationTurboModule.kt` (Android) |
| 20 | +3. iOS: `RNNCommandsHandler` → `RNNViewControllerFactory` → UIKit controllers |
| 21 | +4. Android: `Navigator` → `LayoutFactory` → View-based controllers (no Fragments) |
| 22 | + |
| 23 | +Read [ARCHITECTURE.md](../../ARCHITECTURE.md) for the full overview. |
| 24 | + |
| 25 | +## Key Cross-Layer Mappings |
| 26 | + |
| 27 | +### Layout Types → Native Controllers |
| 28 | + |
| 29 | +| JS Layout Type | iOS Controller | Android Controller | |
| 30 | +|----------------|---------------|-------------------| |
| 31 | +| `component` | `RNNComponentViewController` | `ComponentViewController` | |
| 32 | +| `stack` | `RNNStackController` (UINavigationController) | `StackController` | |
| 33 | +| `bottomTabs` | `RNNBottomTabsController` (UITabBarController) | `BottomTabsController` | |
| 34 | +| `sideMenu` | `RNNSideMenuViewController` (MMDrawerController) | `SideMenuController` (DrawerLayout) | |
| 35 | +| `topTabs` | `RNNTopTabsViewController` | `TopTabsController` (ViewPager) | |
| 36 | +| `splitView` | `RNNSplitViewController` | N/A (iOS only) | |
| 37 | +| `externalComponent` | `RNNExternalViewController` | `ExternalComponentViewController` | |
| 38 | + |
| 39 | +### Options → Presenters |
| 40 | + |
| 41 | +Each controller type has a Presenter that applies options to views: |
| 42 | + |
| 43 | +| iOS Controller | iOS Presenter | Android Presenter | |
| 44 | +|----------------|--------------|-------------------| |
| 45 | +| `RNNComponentViewController` | `RNNComponentPresenter` | `ComponentPresenter` | |
| 46 | +| `RNNStackController` | `RNNStackPresenter` + `TopBarPresenter` | `StackPresenter` | |
| 47 | +| `RNNBottomTabsController` | `RNNBottomTabsPresenter` | `BottomTabsPresenter` | |
| 48 | +| `RNNSideMenuViewController` | `RNNSideMenuPresenter` | `SideMenuPresenter` | |
| 49 | + |
| 50 | +### Events (same names both platforms) |
| 51 | + |
| 52 | +| Event | Trigger | |
| 53 | +|-------|---------| |
| 54 | +| `RNN.ComponentDidAppear` | Screen becomes visible | |
| 55 | +| `RNN.ComponentDidDisappear` | Screen hidden | |
| 56 | +| `RNN.NavigationButtonPressed` | TopBar button tap | |
| 57 | +| `RNN.BottomTabSelected` | Tab changed | |
| 58 | +| `RNN.ModalDismissed` | Modal dismissed | |
| 59 | +| `RNN.ScreenPopped` | Screen popped from stack | |
| 60 | +| `RNN.CommandCompleted` | Any command finished | |
| 61 | + |
| 62 | +## Where to Find Things |
| 63 | + |
| 64 | +### By task: "I need to fix/change X" |
| 65 | + |
| 66 | +| Task | JS File(s) | iOS File(s) | Android File(s) | |
| 67 | +|------|-----------|------------|----------------| |
| 68 | +| Command execution | `src/commands/Commands.ts` | `ios/RNNCommandsHandler.mm` | `react/NavigationTurboModule.kt` | |
| 69 | +| Layout creation | `src/commands/LayoutTreeParser.ts` | `ios/RNNViewControllerFactory.mm` | `options/LayoutFactory.java` | |
| 70 | +| Options processing | `src/commands/OptionsProcessor.ts` | `ios/RNNNavigationOptions.mm` | `options/Options.java` | |
| 71 | +| Options application | — | `ios/*Presenter.mm` | `viewcontrollers/*Presenter.java` | |
| 72 | +| TopBar | `src/interfaces/Options.ts` (TopBarOptions) | `ios/TopBarPresenter.mm`, `ios/RNNUIBarButtonItem.mm` | `views/stack/topbar/` | |
| 73 | +| Bottom tabs | `src/interfaces/Options.ts` (BottomTabsOptions) | `ios/RNNBottomTabsPresenter.mm` | `viewcontrollers/bottomtabs/` | |
| 74 | +| Modals | `src/commands/Commands.ts` | `ios/RNNModalManager.mm` | `viewcontrollers/modal/ModalStack.java` | |
| 75 | +| Overlays | `src/commands/Commands.ts` | `ios/RNNOverlayManager.mm` | `viewcontrollers/overlay/OverlayManager.kt` | |
| 76 | +| Animations | `src/interfaces/Options.ts` (AnimationOptions) | `ios/ScreenAnimationController.mm` | `viewcontrollers/stack/StackAnimator.kt` | |
| 77 | +| React view rendering | — | `ios/RNNReactView.mm` | `react/ReactView.java` | |
| 78 | +| Events to JS | `src/adapters/NativeEventsReceiver.ts` | `ios/RNNEventEmitter.mm` | `react/events/EventEmitter.java` | |
| 79 | +| Component registration | `src/components/ComponentRegistry.ts` | — | — | |
| 80 | + |
| 81 | +### By directory |
| 82 | + |
| 83 | +- **`src/`** — JS public API, commands, processing pipeline. See [src/ARCHITECTURE.md](../../src/ARCHITECTURE.md) |
| 84 | +- **`ios/`** — All Obj-C/C++ native code. See [ios/ARCHITECTURE.md](../../ios/ARCHITECTURE.md) |
| 85 | +- **`ios/TurboModules/`** — New architecture entry points (`RNNTurboModule`, `RNNTurboManager`, `RNNTurboCommandsHandler`) |
| 86 | +- **`android/src/main/java/com/reactnativenavigation/`** — All Java/Kotlin native code. See [android/ARCHITECTURE.md](../../android/ARCHITECTURE.md) |
| 87 | +- **`playground/`** — Demo app for development and E2E tests |
| 88 | +- **`playground/src/screens/`** — Test screens exercising every feature |
| 89 | +- **`playground/e2e/`** — Detox E2E tests |
| 90 | + |
| 91 | +## Options Resolution Order |
| 92 | + |
| 93 | +Options merge bottom-up: |
| 94 | +1. Component's static `options` (from class or `Navigation.registerComponent`) |
| 95 | +2. Parent controller options (stack, tabs, etc.) |
| 96 | +3. Default options (from `Navigation.setDefaultOptions()`) |
| 97 | + |
| 98 | +`mergeOptions()` applies at runtime and takes highest priority. |
| 99 | + |
| 100 | +## JS Processing Pipeline (exact order) |
| 101 | + |
| 102 | +``` |
| 103 | +API layout → OptionsCrawler.crawl() → LayoutProcessor.process() |
| 104 | + → LayoutTreeParser.parse() → LayoutTreeCrawler.crawl() |
| 105 | + → OptionsProcessor (colors, assets, custom) → NativeCommandsSender |
| 106 | +``` |
| 107 | + |
| 108 | +## iOS Patterns |
| 109 | + |
| 110 | +- All controllers conform to `RNNLayoutProtocol` |
| 111 | +- `RNNBasePresenter` subclasses apply options — `applyOptionsOnInit:`, `applyOptions:`, `mergeOptions:resolvedOptions:` |
| 112 | +- Commands run on main thread (`RCTExecuteOnMainQueue`) |
| 113 | +- React views: `RNNReactView` wraps `RCTSurfaceHostingView` (new arch) |
| 114 | +- Overlays use separate `UIWindow` instances (`RNNOverlayWindow`) |
| 115 | +- `RNNReactComponentRegistry` caches React component instances |
| 116 | + |
| 117 | +## Android Patterns |
| 118 | + |
| 119 | +- View-based, NOT Fragment-based |
| 120 | +- All commands dispatched via `UiThread.post()` |
| 121 | +- `ViewController<T extends ViewGroup>` is the base — `createView()` is abstract |
| 122 | +- `ParentController` extends `ChildController` extends `ViewController` |
| 123 | +- Bottom tabs use `AHBottomNavigation` library |
| 124 | +- Three root layouts in `NavigationActivity`: rootLayout, modalsLayout, overlaysLayout |
| 125 | +- Tab attachment modes: `Together`, `OnSwitchToTab`, `AfterInitialTab` |
| 126 | + |
| 127 | +## Development Workflow |
| 128 | + |
| 129 | +### Playground app |
| 130 | +- `yarn start` — Metro bundler |
| 131 | +- `yarn xcode` — Open iOS project |
| 132 | +- `yarn studio` — Open Android project |
| 133 | +- `yarn pod-install` — Install iOS pods |
| 134 | + |
| 135 | +### Testing |
| 136 | +- `yarn test-js` — Jest unit tests |
| 137 | +- `yarn test-unit-ios` — iOS native unit tests (XCTest) |
| 138 | +- `yarn test-unit-android` — Android native unit tests (JUnit + Robolectric) |
| 139 | +- `yarn test-e2e-ios` / `yarn test-e2e-android` — Detox E2E tests |
| 140 | + |
| 141 | +### Building |
| 142 | +- `yarn bob build` — Builds `src/` → `lib/` (ESM + types) |
| 143 | +- Codegen config: `rnnavigation` in `package.json` |
| 144 | + |
| 145 | +## Common Gotchas |
| 146 | + |
| 147 | +- iOS uses UIKit subclasses (UINavigationController, UITabBarController); Android uses custom View hierarchy |
| 148 | +- `splitView` is iOS-only |
| 149 | +- Side menu: iOS uses MMDrawerController (3rd party); Android uses DrawerLayout (native) |
| 150 | +- Options that exist in JS types may not be implemented on both platforms — check the presenter |
| 151 | +- `passProps` are stored in JS `Store`, not sent to native (cleared before bridge crossing) |
| 152 | +- The `lib/` folder is generated — never edit it, edit `src/` instead |
0 commit comments