Alternative API for defining navigators

[brentvatne]

I've noticed that people have had a hard time grasping how nesting navigators works in React Navigation, and part of that might be due to the relatively flat appearance of defining navigators with functions and then passing the navigators in as screens to others.

It might be good to provide a library that lets people use a JSX oriented API that gives a more natural sense of nesting. A proof of concept of this can be found here: https://snack.expo.io/@notbrent/dsl

See:

// Notice in this example that the modal is inside of the tabs -- the tabs UI
// appears on top of the modal profile stack
const Navigation = createAppContainer(
  <BottomTabs>
    <Route name="Home" path="/" screen={HomeScreen} />
    <Route name="Profile" path="/profile">
      <Stack mode="modal">
        <Route
          name="ProfileShow"
          path="/"
          screen={ProfileScreen}
          navigationOptions={{ title: 'Profile' }}
        />
        <Route name="Settings" path="/settings">
          <Stack navigationOptions={{ header: null }}>
            <Route
              name="SettingsShow"
              path="/"
              screen={SettingsScreen}
              navigationOptions={{ title: 'Settings' }}
            />
            <Route
              name="About"
              path="/"
              screen={AboutScreen}
              navigationOptions={{ title: 'About' }}
            />
          </Stack>
        </Route>
      </Stack>
    </Route>
  </BottomTabs>
);

And compare it with

// Here we put the modal stack at the root so the stack ui appears on top of
// the tabs rather than underneat the tabs
const AlternativeNavigation = createAppContainer(
  <Stack mode="modal" headerMode="none">
    <Route name="Tabs">
      <BottomTabs>
        <Route name="Home" path="/" screen={HomeScreen} />
        <Route name="Profile" path="/profile">
          <Stack>
            <Route
              name="ProfileShow"
              path="/"
              screen={ProfileScreen}
              navigationOptions={{ title: 'Profile' }}
            />
          </Stack>
        </Route>
      </BottomTabs>
    </Route>
    <Route name="Settings" path="/settings">
      <Stack>
        <Route
          name="SettingsShow"
          path="/"
          screen={SettingsScreen}
          navigationOptions={{ title: 'Settings' }}
        />
        <Route
          name="About"
          path="/"
          screen={AboutScreen}
          navigationOptions={{ title: 'About' }}
        />
      </Stack>
    </Route>
  </Stack>
);

at a glance it may be easier to understand than the alternative of using createXNavigator

[ericvicenti]

Definitely interesting! You could even throw an error in the render function, so that people will get clear feedback if they attempt to render a <Stack> or something inside their app

[satya164]

I think if we are thinking about a new API for navigators, there are few things worth addressing

• Should be able to dynamically configure navigators and screens
• Should be able to dynamically render routes
• Should work well with static type checkers

While a JSX based API is nice, the current approach will still lack the above things (and type checking will be worse with JSX). Also maybe this can be confusing since it's not common to use JSX outside a component.

I think we should do something like come up with a dynamic JSX based API and provide a backward compatible abstraction over it for defining routes statically.

I'm not very familiar with the codebase yet, so it'll be great if you can mention which things get easier because of the static API. Is it possible to have the same with dynamic API?

[wokalski]

I wanted to open an issue as suggested by @ericvicenti but using react-reconciler is a possible solution to this issue (+ it covers all points raised by @satya164). That said, I am not sure what backwards compatibility story would be. What's more I haven't used react-navigation for more than a year now.

It might be good to provide a library that lets people use a JSX oriented API that gives a more natural sense of nesting.

I think if we are thinking about a new API for navigators, there are few things worth addressing

• Should be able to dynamically configure navigators and screens
• Should be able to dynamically render routes
• Should work well with static type checkers

The problem

Arguably the hardest thing about building applications is structuring the way data is managed in them. React attempts to give an answer to that by allowing us to create a tree of components which encapsulate data management along with rendering and other effects. Ideally, we keep state as low as possible so that reusing our components and reasoning about them is simple. Let's take a look at this simple screen as an example:

That said, this representation of data is only possible if the state lives within the Lists component. In the real world the data structure looks more like this:

The data lives outside of the components themselves because it's shared by them. What this practically means is that components manage the data but don't own it directly. As a consequence, the data has to leave the (React's) reactive realm and be managed separately. And since data management is the hardest thing when you build apps, we tend to make very costly mistakes here.

The solution

What if we used React for the problem that React attempts to solve!? If we zoom back, what we really have is a combination of components and state that live in sort of different realms.

What's more, putting data where it belongs (components) also allows us to manage (and share logic) between views and navigation. We can easily understand the structure of data in application by inspecting who owns it. We can even think about (crazy things like) using suspense for navigation. Incidentally it also practically removes the learning curve for React Navigation. If you know React, you know React Navigation. Your whole application becomes a function of state -> UI.

The drawbacks

Besides problematic backwards compatibility story I don't see major drawbacks.

The flaws

Modelling stack navigators with React elements is tricky. In cases where a React element contains a fragment or an array it's not obvious what the semantics should be (or if it should be disallowed.)

I am probably naive with my list of possible flaws/drawbacks but I'd appreciate considering this proposal along with any feedback (especially challenging my assumptions).

[wokalski]

I'd like to address two more concrete problems, as mentioned by @satya164, separately:

1. Static typing:
   Well, it all becomes just react. You can pass props as expected, it's all typed just like the rest of you React code.

2. Dynamism:
   Dynamism is implied with this approach but it's still easy to understand the overall structure just like with the static config; just follow the navigation components!

[wokalski]

It also slightly opens the door to not rendering views which are off screen (possibly opt in). If the data lives within navigation components the majority of state will be preserved even if we don't render a subtree. We could create a way to explicitly retain some parts of the data (and maybe even provide wrapper navigation components for common cases like rendering lists and preserving the scroll position)

[ericvicenti]

Thanks for getting this discussion (re)started!

It is certainly an interesting idea to hoist up application state and passing that through the navigation system so that your whole app's state can be easily managed with React. I'm not sure what that would look like.

@satya164 has a cool new prototype that allows the following API:

function App() {
  return (
    <NavigationContainer>
      <StackNavigator initialRouteName="home">
        <Screen name="settings" component={Settings} />
        <Screen
          name="profile"
          component={Profile}
          options={{ title: 'John Doe' }}
        />
        <Screen name="home">
          {() => (
            <TabNavigator initialRouteName="feed">
              <Screen name="feed" component={Feed} />
              <Screen name="article" component={Article} />
              <Screen name="notifications">
                {props => <Notifications {...props} />}
              </Screen>
            </TabNavigator>
          )}
        </Screen>
      </StackNavigator>
    </NavigationContainer>
  );
}

Does this seem similar to what you have in mind?

See his prototype here: https://github.com/react-navigation/navigation-ex

[wokalski]

No, it is quite different. What I forgot to include in the description is that this causes navigation tree to be defined declaratively instead of side effects (like push/pop). It is just react but for navigation instead of views.

import { StackNavigator, Screen } from "react-navigation";

function Profile(props) {
  let data = useMagicalHook(props);
  return <Screen name="Profile" contentView={<SomeComponent data />} />;
}

function Settings(props) {
  let data = useMagicalHook(props);
  return <Screen name="Settings" contentView={<OtherComponent data />} />;
}

function Home(props) {
  let profile = useGetProfile();
  let [showProfile, setShowProfile] = useState(false);
  let [showSettings, setShowSettings] = useState(false);
  return (
    <Screen
      contentView={
        <View>
          <ProfileBanner
            onClick={profile ? () => setShowProfile(true) : null}
            onSettingsClick={() => setShowSettings(true)}
          />
          <TabNavigatorAPIToBeDone />
        </View>
      }
      name="Home"
    >
      {showProfile ? <Profile profile={profile} /> : null}
      {showSettings ? <Settings /> : null}
    </Screen>
  );
}

function App() {
  return (
    <StackNavigator>
      <Home />
      /* The semantics with multiple elements here remain unclear. Maybe it'd be
      better not to use JSX but normal functions (but still use react behind the
      scenes) */
    </StackNavigator>
  );
}

Edit: notice that handling going back is not included here, nor is it very clean. But I believe it already shows the approach and its benefits. Notice how we can pass props between components.

[ericvicenti]

I wonder how this would look with a large app. I suspect that it would become rather tedious to set up functions like setShowSettings for every route in your app, and would become crazy with larger apps than a single stack. When you loose the concept of routes, I think you also loose a lot of react-navigation's utility. But, maybe there are other ways to fix those problems.

If you want to experiment with this, you can use the raw react-navigation views directly, such as
Satya's new Stack component: https://github.com/react-navigation/stack/blob/%40satya164/reanimated-stacks/src/views/Stack/Stack.tsx#L31-L59

[wokalski]

I wonder how this would look with a large app. I suspect that it would become rather tedious to set up functions like setShowSettings for every route in your app, and would become crazy with larger apps than a single stack

I agree it's tedious and I'm 100% sure it can be improved! Notice, that usually it's not a boolean flag that determines if a sub route is shown but a state transition. Like you have tweets list and you set a selected tweet. If selected is null you don't show a sub route. Otherwise you do. For the simple cases, we can figure out some utilities. I'll take a look at the standalone stack component. It looks perfect for the experimentation.

Also, it's not any more tedious (or error prone) than calling push/pop. I'd argue even "ugly" boolean flags are much better than the effectful APIs. That way you have a single point of declaring visibility.

[ericvicenti]

Good luck! It would be great to see an example app that demonstrates this idea with a slightly complicated navigation structure.

[wokalski]

@ericvicenti do you have any react-navigation examples that you consider slightly complicated?

[ericvicenti]

The playground in the react-navigation repo is a modal stack with examples that get pushed. One of those examples is a Stack navigator within each tab of a Tab navigator. So thats StackNavigator > TabsNavigator > StackNavigator

https://github.com/react-navigation/react-navigation/blob/master/examples/NavigationPlayground/src/StacksInTabs.tsx

But a lot of complexity can be seen with just nesting a stack navigators, aka a push-style stack inside of a modal stack.