Refactor auth flow guide

satya164 · satya164 · commit 826bd495bcdb · 2020-02-21T06:10:34.000+01:00
diff --git a/website/versioned_docs/version-5.x/auth-flow.md b/website/versioned_docs/version-5.x/auth-flow.md
@@ -18,19 +18,86 @@ Most apps require that a user authenticate in some way to have access to data as
 
 This is the behavior that we want from the authentication flow: when users sign in, we want to throw away the state of the authentication flow and unmount all of the screens related to authentication, and when we press the hardware back button we expect to not be able to go back to the authentication flow.
 
+## Conditionally define our screens
+
+In our navigator, we can conditionally render appropriate screens. For our case, let's say we have 3 screens:
+
+- `SplashScreen` - This will show a splash or loading screen when we're restoring the token.
+- `SignInScreen` - This is the screen we show if the user isn't signed in already (we couldn't find a token).
+- `HomeScreen` - This is the screen we show if the user is already signed in.
+
+So our navigator will look like:
+
+```js
+if (state.isLoading) {
+  // We haven't finished checking for the token yet
+  return <SplashScreen />;
+}
+
+return (
+  <Stack.Navigator>
+    {state.userToken == null ? (
+      // No token found, user isn't signed in
+      <Stack.Screen
+        name="SignIn"
+        component={SignInScreen}
+        options={{
+          title: 'Sign in',
+          // When logging out, a pop animation feels intuitive
+          // You can remove this if you want the default 'push' animation
+          animationTypeForReplace: state.isSignout ? 'pop' : 'push',
+        }}
+      />
+    ) : (
+      // User is signed in
+      <Stack.Screen name="Home" component={HomeScreen} />
+    )}
+  </Stack.Navigator>
+);
+```
+
+In the above snippet, `isLoading` means that we're still checking if we have a token. This can usually be done by checking if we have a token in `AsyncStorage` and validating if token. After we get the token and if it's valid, we need to set the `userToken`. We also have another state called `isSignout` to have a different animation on sign out.
+
+The main thing to notice is that we're conditionally defining screens based on these state variables:
+
+- `SignIn` screen is only defined if `userToken` is `null` (user is not signed in)
+- `Home` screen is only defined if `userToken` is non-null (user is signed in)
+
+This takes advantage of a new feature in React Navigation: being able to dynamically define and alter the screen definitions of a navigator based on props or state. The example shows stack navigator, but you can use the same approach with any navigator.
+
+Here, we're conditionally defining one screen for each case. But you could also define multiple screens. For example, you probably want to define password reset, signup, etc screens as well when the user isn't signed in. Similarly for the screens accessible after sign in, you probably have more than one screen. We can use `React.Fragment` to define multiple screens:
+
+```js
+state.userToken == null ? (
+  <>
+    <Stack.Screen name="SignIn" component={SignInScreen} />
+    <Stack.Screen name="SignUp" component={SignUpScreen} />
+    <Stack.Screen name="ResetPassword" component={ResetPassword} />
+  </>
+) : (
+  <>
+    <Stack.Screen name="Home" component={HomeScreen} />
+    <Stack.Screen name="Profile" component={ProfileScreen} />
+  </>
+);
+```
+
+This pattern has been in use by other routing libraries such as React Router for a long time, and is commonly knows as "Protected routes". Here, our screens which need the user to be logged in are "protected" and cannot be navigated to by other means if the user is not logged in.
+
 ## Implement the logic for restoring the token
 
-In our component, we'll keep 2 states:
+From the previous snippet, we can see that we need 3 state variables:
 
 - `isLoading` - We set this to `true` when we're trying to check if we already have a token saved in `AsyncStorage`
+- `isSignout` - We set this to `true` when user is signing out, otherwise set it to `false`
 - `userToken` - The token for the user. If it's non-null, we assume the user is logged in, otherwise not.
 
 So we need to:
 
 - Add some logic for restoring token, sign in and sign out
 - Expose methods for sign in and sign out to other components
 
-We'll use `React.useReducer` and `React.useContext` in this guide. But if you're using a state management library such as Redux or Mobx, you can use them for this functionality instead. In fact, in bigger apps, a global state management library is more suitable for storing authentication tokens.
+We'll use `React.useReducer` and `React.useContext` in this guide. But if you're using a state management library such as Redux or Mobx, you can use them for this functionality instead. In fact, in bigger apps, a global state management library is more suitable for storing authentication tokens. You can adapt the same approach to your state management library.
 
 First we'll need to create a context for auth where we can expose necessary methods:
 
@@ -42,6 +109,8 @@ const AuthContext = React.createContext();
 
 So our component will look like this:
 
+<samp id="auth-flow" />
+
 ```js
 import * as React from 'react';
 import AsyncStorage from '@react-native-community/async-storage';
@@ -123,99 +192,20 @@ export default function App({ navigation }) {
 
   return (
     <AuthContext.Provider value={authContext}>
-      {/* We'll render navigator content here */}
+      <Stack.Navigator>
+        {state.userToken == null ? (
+          <Stack.Screen name="SignIn" component={SignInScreen} />
+        ) : (
+          <Stack.Screen name="Home" component={HomeScreen} />
+        )}
+      </Stack.Navigator>
     </AuthContext.Provider>
   );
 }
 ```
 
-## Render the navigator content
-
-In our navigator, we can conditionally render appropriate screens. For our case, let's say we have 3 screens:
-
-- `SplashScreen` - This will show a splash or loading screen when we're restoring the token.
-- `SignInScreen` - This is the screen we show if the user isn't signed in already (we couldn't find a token).
-- `HomeScreen` - This is the screen we show if the user is already signed in.
-
-So our navigator will look like:
-
-<samp id="auth-flow" />
-
-```js
-if (state.isLoading) {
-  // We haven't finished checking for the token yet
-  return <SplashScreen />;
-}
-
-return (
-  <AuthContext.Provider value={authContext}>
-    <Stack.Navigator>
-      {state.userToken == null ? (
-        // No token found, user isn't signed in
-        <Stack.Screen
-          name="SignIn"
-          component={SignInScreen}
-          options={{
-            title: 'Sign in',
-            // When logging out, a pop animation feels intuitive
-            // You can remove this if you want the default 'push' animation
-            animationTypeForReplace: state.isSignout ? 'pop' : 'push',
-          }}
-        />
-      ) : (
-        // User is signed in
-        <Stack.Screen name="Home" component={HomeScreen} />
-      )}
-    </Stack.Navigator>
-  </AuthContext.Provider>
-);
-```
-
-In the above code snippet, we're conditionally defining screens:
-
-- `SignIn` screen is only defined if `userToken` is `null`
-- `Home` screen is only defined if `userToken` is non-null
-
-This takes advantage of a new feature in React Navigation: being able to dynamically define and alter the screen definitions of a navigator based on props or state. The example shows stack navigator, but you can use the same approach with any navigator.
-
-> Note: The following explanation is useful for people coming from older versions of React Navigation. If React Navigation 5 is your first version, then you can skip to the next section.
-
-In earlier versions of React Navigation, there were 2 ways to handle this:
-
-1. Keep multiple navigators and use switch navigator to switch the active navigator to a different one upon login (recommended)
-2. Reset the state of the navigator to the desired screens upon login
-
-Both of these approaches were imperative. We needed to update the state to save your token, and then do a `navigate` or `reset` to change screens manually. Seems reasonable, right? But what happens when the user logs out? We need to update the state to delete the token, then `navigate` or `reset` again manually to show the login screen. We have to imperatively do the task twice already. Add more scenarios to this (e.g. unverified user, guest etc.) and it becomes even more complex.
-
-But with the above approach, you can declaratively say which screens should be accessible if user is logged in and which screens shouldn't be. If the user logs in or logs out, you update the `userToken` in state and the correct screens are shown automatically.
-
-To summarize the benefits:
-
-- No need for manually navigating to correct screen on log in or log out, correct screens are shown automatically.
-- If the user is not logged in, it's impossible to navigate to screens which need the user to be logged in (e.g. from a deep link, restoring persisted state), which means you don't need to deal with inconsistent states.
-- Since all our screens are under the stack navigator, we get smooth animations after log in or log out unlike the abrupt screen change with switch navigator.
-
-This pattern has been in use by other routing libraries such as React Router for a long time, and is commonly knows as "Protected routes". Here, our screens which need the user to be logged in are "protected" and cannot be navigated to by other means if the user is not logged in.
-
 ## Fill in other components
 
-We're conditionally defining one screen for each case here. But you could define multiple screens here too. For example, you probably want to defined password reset, signup, etc screens as well when the user isn't signed in. Similarly for your app, you probably have more than one screen. We can use `React.Fragment` - to define multiple screens:
-
-```js
-state.userToken == null ? (
-  <>
-    <Stack.Screen name="SignIn" component={SignInScreen} />
-    <Stack.Screen name="SignUp" component={SignUpScreen} />
-    <Stack.Screen name="ResetPassword" component={ResetPassword} />
-  </>
-) : (
-  <>
-    <Stack.Screen name="Home" component={HomeScreen} />
-    <Stack.Screen name="Profile" component={ProfileScreen} />
-  </>
-);
-```
-
 We won't talk about how to implement the text inputs and buttons for the authentication screen, that is outside of the scope of navigation. We'll just fill in some placeholder content.
 
 ```js
diff --git a/website/versioned_docs/version-5.x/upgrading-from-4.x.md b/website/versioned_docs/version-5.x/upgrading-from-4.x.md
@@ -304,9 +304,24 @@ export default function App() {
 }
 ```
 
-The new approach is more maintainable and removes the need for something like Switch Navigator. So it has been removed.
+In earlier versions of React Navigation, there were 2 ways to handle this:
 
-See [Authentication flows](auth-flow.html) for more info on implementing authentication flows.
+1. Keep multiple navigators and use switch navigator to switch the active navigator to a different one upon login (recommended)
+2. Reset the state of the navigator to the desired screens upon login
+
+Both of these approaches were imperative. We needed to update the state to save your token, and then do a `navigate` or `reset` to change screens manually. Seems reasonable, right? But what happens when the user logs out? We need to update the state to delete the token, then `navigate` or `reset` again manually to show the login screen. We have to imperatively do the task twice already. Add more scenarios to this (e.g. unverified user, guest etc.) and it becomes even more complex.
+
+But with the above approach, you can declaratively say which screens should be accessible if user is logged in and which screens shouldn't be. If the user logs in or logs out, you update the `userToken` in state and the correct screens are shown automatically.
+
+To summarize the benefits:
+
+- No need for manually navigating to correct screen on log in or log out, correct screens are shown automatically.
+- If the user is not logged in, it's impossible to navigate to screens which need the user to be logged in (e.g. from a deep link, restoring persisted state), which means you don't need to deal with inconsistent states.
+- Since all our screens are under the stack navigator, we get smooth animations after log in or log out unlike the abrupt screen change with switch navigator.
+
+So, the new approach covers more edge cased and removes the need for something like Switch Navigator. So it has been removed.
+
+See [Authentication flows](auth-flow.html) for a guide on implementing authentication flows.
 
 ## Global props with `screenProps`
 
