react-navigation / react-navigation/react-navigation.github.io

Documentation for web use is confusing and/or incomplete

Open
#531 0 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
324
Forks
2k
PR merge metrics
No merged PRs in 30d

Description

I began exploring bringing my RN project to the web via react-native-web and quickly hit a stumbling block with react-navigation due to the confusing or incomplete documentation about web usage. I'm referring to the documentation here:

https://reactnavigation.org/docs/en/web-support.html

Specifically the following are/were points of confusion

  1. The "with react native web" section only mentions using expo. React-native-web seems to be the de-facto mechanism to bring RN projects to web in the community and I would guess that a lot (or most) projects don't use non-ejected expo. How does react navigation web support relate to react-native-web in general outside of the context of expo?
  2. The "with standard web tools" section isn't really clear about what "standard web tools" means in this context. It seems to refer to using react-native-web or a plain web browser with a bundler like webpack?
  3. The package names are confusing and I couldn't find any clarification. There's react-navigation @react-navigation/core, @react-navigation/web and a bunch of others on NPM with no indication that I could find of what the difference between them is. The @react-navigation packages seem to be lower/older versions but are recommended for web use in the docs. Which package is for which usage and which packages are old/deprecated?
  4. How does using the packages in the example @react-navigation/core and @react-navigation/web work alongside "normal" react-navigation in a react-native-web project? This appears to be missing entirely from the docs and I had to hack/find a solution across a lot of different issues in a bunch of repos.
  5. Are there TS definitions for the @react-navigation packages?

Here's how I've ended up configuring my navigator but honestly I have no idea if this is the best/correct/compatible way to do it with react-native-web:

import { createSwitchNavigator } from "@react-navigation/core"
import { createAppContainer } from "react-navigation"
// import { createStackNavigator } from "react-navigation-stack"
import { createBrowserApp } from "@react-navigation/web"

import AuthScreen from "../screens/AuthScreen"
import HomeScreen from "../screens/HomeScreen"
import AuthLoadingScreen from "../screens/AuthLoadingScreen"
import Main from "../../Main"
import { Platform } from "react-native"

const AppStack = createSwitchNavigator({ Home: Main }, { headerMode: "none" })
const AuthStack = createSwitchNavigator({ SignIn: AuthScreen }, { headerMode: "none" })

let appNavigator = createAppContainer(
    createSwitchNavigator(
        {
            AuthLoading: AuthLoadingScreen,
            App: AppStack,
            Auth: AuthStack
        },
        {
            initialRouteName: "AuthLoading"
        }
    )
)

if (Platform.OS == "web") {
    appNavigator = createBrowserApp(
        createSwitchNavigator(
            {
                AuthLoading: AuthLoadingScreen,
                App: AppStack,
                Auth: AuthStack
            },
            {
                initialRouteName: "AuthLoading"
            }
        )
    )
}
export default appNavigator

Some clarification on if this is a good/acceptable approach would be appreciated. Once I figure out the answers to these questions myself perhaps I'll be able to submit a documentation PR to help others avoid this confusion.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the web-support documentation at reactnavigation.org/docs/en/web-support.html and review the package examples referenced in the issue. Clarify how react-native-web relates to Expo and standard web tools, distinguish the navigation packages and TypeScript support, and document the recommended configuration. Done means the listed questions are answered without requiring readers to search across other repositories.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, react, react-native
Domain
documentation, mobile-dev, web-dev
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.