React Router Native

A routing library for React Native that strives for sensible API parity with react-router.

Background

React Router community decided that a reducer-based paradigm similar to that of NavigationExperimental is better suited to native navigation. Transition to a reducer-based paradigm is also being discussed for the web. On the other hand, NavigationExperimental has no intention to support a React Router-like interface and leaves the navigation state up to the developer to maintain.

A declarative API removes the need to write boilerplate code and speeds up development. React Router Native follows React's Learn Once, Write Anywhere principle by providing a superset of React Router's API that marries React Router to NavigationExperimental.

Goals

URL Driven Development
Learn once, write anywhere: knowledge and proven idioms from react-router can be reused while extending them as necessary to allow navigation semantics unique to native platforms
First class deep linking support

Note: This project contains components that are currently under active development and considered experimental—aka use in production at your own risk. Documentation is still a work-in-progress, and pull requests are accepted gratefully!

Installation

Using npm:

$ npm install --save react-router-native react-router

Do not let npm confuse you: there used to be another project with the same name that the previous owner nuked. Unfortunately, removing or re-publishing old versions is no longer supported by npm. So packages that are tagged < v2.0.0 on npm are artifacts of a different project, and the first stable version of this library will be released as v2.0.0 and strictly follow the React Versioning Scheme afterwards.

Example

The example app from the GIF can be found at examples/Aviato. You can run it as follows:

git clone https://github.com/jmurzy/react-router-native
cd react-router-native/examples/Aviato
npm install
react-native run-ios

Look at app/routes.js and play around with the app to get a feel for what's possible. The address bar shown in the demo is used for development only and can be disabled by removing the addressBar prop from the <Router> component.

Usage

// index.[ios|android].js

import { AppRegistry } from 'react-native';
import { Router, Route, TabsRoute } from 'react-router-native';

const App = (props) => (/*...*/);
const About = (props) => (/*...*/);
const AboutHeader = (props) => (/*...*/);
const Users = (props) => (/*...*/);
const User = (props) => (/*...*/);
const UserHeader = (props) => (/*...*/);
const NoMatch = (props) => (/*...*/);

const routes = (
  /* Address Bar can be toggled on or off by setting the addressBar prop */
  <Router addressBar>
    <TabsRoute
      path="app"
      component={App}
      transition="horizontal-pager"
    >
      <Route path="/" component={About} overlayComponent={AboutHeader}/>
      <Route path="users" component={Users} overlayComponent={UserHeader}>
        <Route path="/user/:userId" component={User}/>
      </Route>
    </TabsRoute>
    <Route path="*" component={NoMatch}/>
  </Router>
);

AppRegistry.registerComponent('YourApp', () => () => routes);

Advanced Usage

You can customize behavior of the default reducers that are used to create the navigationState of <Route> or its siblings.

This allows greater customizations on how <Link> behaves for a particular route and is especially useful for nested <StackRoute>'s where default action doesn't always lead to the intended behavior, or <TabsRoute>'s where double-taps should reset the navigationState of a nested <StackRoute>.

const reducer = (
  state: EnhancedNavigationState,
  action: NavigationAction
): EnhancedNavigationState => ({
  /* ... */
});

<TabsRoute path="/" component={Component} reducer={reducer}/>

Platform Support

React Router Native is cross-platform. It supports all platforms that NavigationExperimental supports.

Contributing

In order to hack on the library code and sync it into examples/Aviato/node_modules run npm run sync (depends on npm i -g sane). The library code is specified as a local dependency in the example's package.json -- npm link does not work with RN packager right now (it's an open issue).

More info on workflow and setup can be found in CONTRIBUTING.md.

We look forward to your input! 👊

Questions?

Feel free to reach out to me on Twitter @jmurzy. If you have any questions, please submit an Issue with the "question" tag or come hang out in the React Router Reactiflux Channel and post your request there.

Thanks

React Router Native is based on React Router. Thanks to Ryan Florence @ryanflorence, Michael Jackson @mjackson and all the contributors for their work on react-router and history.

Special thanks to Eric Vicenti @ericvicenti and Hedger Wang @hedgerwang for their work on NavigationExperimental.

jonathanglasmeyer / react-router-native