wix/react-native-navigation: native navigation for React Native, installed by hand

What problem react-native-navigation solves, and who it is for

React Native Navigation provides what the README calls "100% native platform navigation on both iOS and Android for React Native apps". That sentence is the whole pitch, and it is also the boundary. The library does not draw a navigation bar in JavaScript and hope it looks like the platform's. Screens are hosted inside real native containers, so the top bar, the back gesture, the tab bar and the transition animation come from UIKit on iOS and from the Android framework on Android.

The audience is narrow but real. You are building a React Native app that ships to the App Store and Google Play, you have native projects in your repository (the android/ and ios/ directories, not a managed cloud build), and your designers or your users notice when a transition does not match the rest of the operating system. Teams that fit that description get platform behaviour they would otherwise have to approximate.

Teams that do not fit it should stop reading here. If your app runs in Expo Go, or if your build pipeline never touches Xcode or Gradle, a library whose installation guide is titled around editing native files is the wrong dependency. The README is explicit: "integrating it into your app will require editing native files".

How the native container model actually works

The repository layout tells you most of the architecture before you open a source file. There is an android/ directory, an ios/ directory, a ReactNativeNavigation.podspec at the root, and a src/ directory of TypeScript. That is the shape of a native module with a thin JavaScript surface, not a pure JavaScript library.

On the JavaScript side you do not wrap your app in a navigator component the way a JavaScript router would have you do. You register each screen component with a name, then hand the library a layout tree describing what should be on screen. The library passes that tree across the bridge, and the native side builds the corresponding view hierarchy. ARCHITECTURE.md sits at the repository root for readers who want the full picture.

The consequence of this design is that navigation state lives on the native side, not in a React context. That is why the API feels imperative. It also explains why the package ships a separate Mock entry point: because the library talks to native code, unit tests need a substitute, and the package.json exports map exposes "./Mock" with its own types and module paths.

One more detail worth noticing. The package declares "nativePackage": true and ships autolink/ alongside android/ and ios/. Autolinking is the mechanism that wires the native side into your build without you hand-editing every Gradle and Podfile line, and the package exposes a bin entry named rnn-link that points at ./autolink/postlink/run.js.

Installing react-native-navigation and registering a first screen

The README does not reproduce the install steps. It points at the documentation site and says to "Follow the installation guides in the documentation". The commands below are the ones the repository itself exposes, not a substitute for that guide. Read the guide first; the native edits it describes are the part that breaks builds.

The package is published to npm under the name react-native-navigation. The repository's own package.json declares the dependency under that name:

{
  "name": "react-native-navigation",
  "version": "8.8.9",
  "license": "MIT",
  "nativePackage": true
}

The package.json defines a bin entry, rnn-link, which runs ./autolink/postlink/run.js. That is the autolinking step that rewires your native projects after the dependency is installed:

{
  "bin": {
    "rnn-link": "./autolink/postlink/run.js"
  }
}

iOS dependencies are managed through CocoaPods, and the repository exposes a script for it:

{
  "scripts": {
    "pod-install": "yarn w"
  }
}

Once the native side is wired up, a screen is a normal React component that you register under a name. The package's main entry is ./lib/module/index.js and its React Native entry is ./src/index.ts, which is where Navigation is exported from:

{
  "main": "./lib/module/index.js",
  "types": "./lib/typescript/index.d.ts",
  "react-native": "./src/index.ts"
}

If the screen stays blank after this, the usual cause is a mismatch between the registered component name and the name in the layout tree, or an autolink step that did not run.

The native build is the real cost of admission

This is the limitation that decides whether the library is right for you, and it is not a bug. A native navigation library has to be linked into your native binary. That means a working Xcode installation, a working Android toolchain, and a team that is comfortable reading a Podfile or a Gradle file when an upgrade goes wrong.

The requirement line is specific: apps using React Native Navigation "may target iOS 11 and Android 5.0 (API 21)". Development can happen on Windows, macOS or Linux, but a Windows developer cannot build the iOS side locally, so an iOS build machine is part of your infrastructure whether you planned for it or not.

Upgrades are where this hurts. The release history shows patch releases on a steady cadence through 2026, with 8.8.9, 8.8.10 and 8.8.11 landing between June and August. Patch releases are usually safe. Major version jumps are not, because they can move both the JavaScript API and the native integration surface at the same time. If you cannot schedule a native rebuild and a device pass for each upgrade, you will end up pinned to an old version, and pinned native modules age badly as React Native itself moves.

The wrong-tool case is equally clear. If your team has no one who can debug a failed pod install or a Gradle sync error, a JavaScript navigation library will cost you less over a year, even if its transitions are less faithful.

react-native-navigation versus JavaScript navigation libraries

The alternative most teams compare against is a JavaScript navigation library, typically React Navigation. The difference is not quality, it is where the pixels come from. A JavaScript router composes screens from React Native views and animates them with the Animated API or a reanimated layer. React Native Navigation asks the platform to host the screens.

That difference shows up in three places. First, transitions and gestures: the platform's own back swipe and its own animation curves come for free, whereas a JavaScript implementation has to reproduce them. Second, the top bar and tab bar: native bars follow platform conventions and accessibility behaviour without extra work. Third, the dependency graph: a JavaScript library installs with one command and upgrades with one command, while this one adds a native module to both builds.

The comparison also cuts the other way. A JavaScript library is easier to test in isolation, easier to run in a browser-based or cloud build environment, and easier to reason about because the navigation state is ordinary React state. React Native Navigation's state lives on the native side, which is why the package has to ship a Mock entry point for tests.

There is a middle option worth naming: a JavaScript router that delegates rendering to native screens through a separate native screens package. It keeps the JavaScript API while gaining some native rendering. It is a different trade-off, not a strictly better one, and it does not give you native top bars.

Maintenance, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-09-14, which is recent. The release cadence supports the same reading: three patch releases between late June and early August 2026. Treat the project as maintained, but read the changelog before each upgrade rather than assuming patches are inert.

The versioning is worth planning around. The package.json in the repository lists version 8.8.9 while the newest published release is 8.8.11, which is normal for a repository between releases but is a reminder to check npm rather than the source tree when you want to know what you will actually install. The README also advertises a snapshot channel on npm, so prerelease builds exist; do not put a snapshot on a release branch.

The licence is MIT, stated in both the README badge section and the package.json "license" field. In practical terms that is permissive: you can ship it in a closed-source app. MIT does not grant trademark rights, and it does not cover the platform SDKs you link against. If your legal team has questions about the native dependencies this pulls in, that is a conversation about your app, not about this licence, and it is not something to resolve from a README.

Editorial conclusion

Adopt react-native-navigation if you need platform-native transitions, native top bars and tab bars, and you are willing to maintain native build configuration for both platforms. Do not adopt it if you build with Expo Go, if you want a JavaScript-only dependency, or if you need a navigation library you can upgrade with a single npm command. Before writing screens, verify three things: that your app targets iOS 11 and Android 5.0 (API 21), that the autolink step ran, since the package ships a bin entry named rnn-link pointing at ./autolink/postlink/run.js, and that registerComponent calls line up with the component names you pass to Navigation.setRoot.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wix/react-native-navigation on GitHub