---
name: rnn-codebase
description: Navigate and work with the react-native-navigation (RNN) codebase. Use when fixing bugs, adding features, tracing command flows, understanding options…
---

# rnn-codebase

Navigate and work with the react-native-navigation (RNN) codebase. Use when fixing bugs, adding features, tracing command flows, understanding options…

# rnn-codebaseby 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 ZIPGitHub

## 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 TypeiOS ControllerAndroid 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 ControlleriOS PresenterAndroid Presenter`RNNComponentViewController``RNNComponentPresenter``ComponentPresenter``RNNStackController``RNNStackPresenter` + `TopBarPresenter``StackPresenter``RNNBottomTabsController``RNNBottomTabsPresenter``BottomTabsPresenter``RNNSideMenuViewController``RNNSideMenuPresenter``SideMenuPresenter`

### Events (same names both platforms)

EventTrigger`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"

TaskJS 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

## More skills from wix
wds-docsby wixWix Design System component reference. Use when building UI with @wix/design-system, choosing components, or checking props and examples. Triggers on "what…wix-appby wixBuild and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins,…wix-cli-app-validationby wixUse when testing app readiness, verifying runtime behavior, or validating before releases and after changes in the code. Triggers include validate, test,…wix-cli-backend-apiby wixCreates HTTP endpoints for Wix CLI apps. Use only when the user specifically asks for a backend endpoint. Use when building REST API endpoints, backend HTTP…wix-cli-backend-eventby wixCreate backend event extensions that respond to Wix events. Use when implementing handlers that run when specific conditions occur on a site. Triggers include…wix-cli-context-providerby wixCreates context provider extensions for Wix CLI apps — logical components (no UI) that expose shared state, functions, and configuration to child site…wix-cli-dashboard-menu-pluginby wixMUST use whenever the user wants to add a clickable menu item, action, or option to an existing Wix dashboard page's more-actions menu, bulk-actions menu, or…wix-cli-dashboard-modalby wixUse when adding popup forms, confirmations, or detail views to Wix dashboards; creating reusable dialog components across dashboard pages; showing…

---

**Source**: https://github.com/wix/react-native-navigation/tree/HEAD/.claude/skills/rnn-codebase
**Author**: wix
**Discovered via**: mcpservers.org