feat: simplify auth-gated deep linking with React Navigation

piaccho · piaccho · commit 22dd4ce257d6 · 2026-05-14T12:36:09.000+02:00
diff --git a/README.md b/README.md
@@ -136,17 +136,28 @@ This API requires `DetourProvider` to be mounted above your `NavigationContainer
 See React Navigation docs:
 https://reactnavigation.org/docs/deep-linking?config=static#integrating-with-other-tools
 
-For auth-gated apps, use the helper hook to avoid custom queueing boilerplate:
-
-```ts
-import { useDetourReactNavigationLinking } from "@swmansion/react-native-detour";
-
-const linking = useDetourReactNavigationLinking({
-  config: linkingConfig,
-  canHandleUrl: isSignedIn && isOnboardingCompleted,
-});
+For auth-gated apps, let React Navigation hold the deep link until the right screen is reachable.
+Render screens conditionally on auth/onboarding state and opt in to React Navigation's pending-link
+behavior on the navigator:
+
+```tsx
+<Stack.Navigator UNSTABLE_routeNamesChangeBehavior="lastUnhandled">
+  {isSignedIn
+    ? isOnboardingCompleted
+      ? <>
+          <Stack.Screen name="Tabs" component={TabNavigator} />
+          <Stack.Screen name="Details" component={Details} />
+        </>
+      : <Stack.Screen name="Onboarding" component={Onboarding} />
+    : <Stack.Screen name="SignIn" component={SignIn} />}
+</Stack.Navigator>
 ```
 
+A deep link that arrives while the user is signed-out is parsed, found unreachable (the target
+screen isn't currently rendered), and remembered. When the rendered screen set changes — after
+sign-in, then again after onboarding — React Navigation retries and lands the user on the target.
+See `examples/react-navigation-advanced` for a working setup.
+
 ### Controlling which links Detour processes
 
 Use `linkProcessingMode` to control which link sources the SDK listens to:
@@ -180,7 +191,7 @@ All example apps with Detour SDK integrated live in `examples/`:
 | `examples/expo-router-advanced`      | Expo Router with auth flow and custom native-intent            |
 | `examples/expo-bare`                 | Expo without file-based routing (plain `index.js` entry point) |
 | `examples/react-navigation`          | Minimal React Navigation example                               |
-| `examples/react-navigation-advanced` | React Navigation with auth flow and dedicated helper API       |
+| `examples/react-navigation-advanced` | React Navigation with auth + onboarding gated deep linking     |
 
 The monorepo uses **pnpm workspaces**. Start by installing all dependencies from the repo root:
 
@@ -328,18 +339,11 @@ export type DetourUrlEvent = {
 export type DetourUrlSubscription = {
   remove: () => void;
 };
-
-export type UseDetourReactNavigationLinkingOptions<Config = unknown> = {
-  config: Config;
-  canHandleUrl?: boolean;
-  prefixes?: string[];
-};
 ```
 
 ```js
 Detour.getInitialURL(): Promise<string | undefined>
 Detour.addEventListener("url", (event: DetourUrlEvent) => void): DetourUrlSubscription
-useDetourReactNavigationLinking(options): linking
 ```
 
 ---
diff --git a/examples/react-navigation-advanced/README.md b/examples/react-navigation-advanced/README.md
@@ -6,21 +6,21 @@ This example demonstrates an auth-gated React Navigation app with Detour integra
 
 - Auth flow with conditional screen rendering in a single stack (React Navigation standard pattern).
 - Screens: `SignIn` → `Onboarding` (once per install) → `Tabs` (Home, Explore, Settings) + `Details`.
-- `useDetourGate` exposes auth/onboarding gate state and `useDetourReactNavigationLinking` handles queued URL delivery.
-- React Navigation linking uses the SDK adapter API:
+- React Navigation linking uses the SDK adapter API as the URL source:
   - `Detour.getInitialURL()`
   - `Detour.addEventListener("url", ({ url }) => ...)`
-- The helper hook (`useDetourReactNavigationLinking`) wraps these APIs and removes custom bridge boilerplate.
+- The navigator opts into `UNSTABLE_routeNamesChangeBehavior="lastUnhandled"` so React Navigation remembers a deep link that hits a screen which is not currently rendered and replays it once that screen becomes part of the navigator.
 - Detour processes all link types (universal / app links, custom scheme, deferred) and the app maps routes via React Navigation linking config.
 
 ## Auth-gated deferred link behavior
 
-- If a deferred link arrives and the user is not signed in, the splash hides and `SignIn` is shown. The link is queued.
-- After sign-in, `useDetourGate` re-fires. If onboarding has not been completed yet, `Onboarding` is shown first — the link is still kept alive.
-- After onboarding, `useDetourGate` re-fires again and the queued URL is delivered to React Navigation linking, which resolves `details` (or falls through to `NotFound`).
+- If a deferred link arrives and the user is not signed in, the splash hides and `SignIn` is shown. React Navigation parses the URL, finds `Details` is not currently rendered, and marks the action as the last unhandled one.
+- After sign-in, the rendered screen set changes. If onboarding has not been completed yet, `Onboarding` is shown — `Details` is still not rendered, so the pending link stays remembered.
+- After onboarding, `Details` becomes part of the rendered stack. React Navigation retries the unhandled action and navigates to `Details` (or falls through to `NotFound`).
 
 Reference docs:
-https://reactnavigation.org/docs/deep-linking?config=static#integrating-with-other-tools
+- https://reactnavigation.org/docs/deep-linking?config=static#integrating-with-other-tools
+- https://reactnavigation.org/docs/auth-flow (see `UNSTABLE_routeNamesChangeBehavior`)
 
 ## Test flow
 
diff --git a/examples/react-navigation-advanced/src/App.tsx b/examples/react-navigation-advanced/src/App.tsx
@@ -1,22 +1,22 @@
-import { useEffect, useState } from "react";
+import { useEffect, useMemo } from "react";
 
 import { Text, View } from "react-native";
 
 import * as SplashScreen from "expo-splash-screen";
 import * as SystemUI from "expo-system-ui";
 
-import { NavigationContainer } from "@react-navigation/native";
+import { type LinkingOptions, NavigationContainer } from "@react-navigation/native";
 
 import {
   type Config,
+  DETOUR_LINKING_PREFIX,
+  Detour,
   DetourProvider,
-  useDetourReactNavigationLinking,
 } from "@swmansion/react-native-detour";
 
 import { AuthProvider } from "./auth";
-import { Navigation, linkingConfig } from "./navigation";
+import { Navigation, type RootStackParamList, linkingConfig } from "./navigation";
 import { colors, styles } from "./styles";
-import { useDetourGate } from "./useDetourGate";
 
 const hasCredentials =
   !!process.env.EXPO_PUBLIC_DETOUR_API_KEY && !!process.env.EXPO_PUBLIC_DETOUR_APP_ID;
@@ -53,17 +53,28 @@ SplashScreen.preventAutoHideAsync();
 SystemUI.setBackgroundColorAsync(colors.background);
 
 const AppRoot = () => {
-  const [isNavigationReady, setNavigationReady] = useState(false);
-  const { canHandleDetourLink } = useDetourGate(isNavigationReady);
-  const linking = useDetourReactNavigationLinking({
-    config: linkingConfig,
-    canHandleUrl: canHandleDetourLink,
-  });
+  const linking = useMemo<LinkingOptions<RootStackParamList>>(
+    () => ({
+      prefixes: [DETOUR_LINKING_PREFIX],
+      config: linkingConfig,
+      async getInitialURL() {
+        return await Detour.getInitialURL();
+      },
+      subscribe(listener) {
+        const subscription = Detour.addEventListener("url", ({ url }) => {
+          listener(url);
+        });
+
+        return () => subscription.remove();
+      },
+    }),
+    [],
+  );
 
   return (
     <NavigationContainer
       linking={linking}
-      onReady={() => setNavigationReady(true)}
+      onReady={() => SplashScreen.hideAsync()}
       theme={{
         dark: true,
         colors: {
diff --git a/examples/react-navigation-advanced/src/navigation/index.tsx b/examples/react-navigation-advanced/src/navigation/index.tsx
@@ -68,15 +68,20 @@ function renderAuthScreens({
 }
 
 // Auth flow using conditional screen rendering — equivalent of Stack.Protected in expo-router.
-// When isSignedIn or isOnboardingCompleted changes the navigator resets to the first valid screen.
+// `UNSTABLE_routeNamesChangeBehavior="lastUnhandled"` makes React Navigation remember a deep link
+// that hits a screen which isn't currently rendered (e.g. Details while signed-out) and replay it
+// once the navigator's screen set changes (after sign-in, then again after onboarding).
 // Returns null until auth is loaded from AsyncStorage so the splash covers the empty state.
 export function Navigation() {
   const { isLoaded, isSignedIn, isOnboardingCompleted } = useAuth();
 
   if (!isLoaded) return null;
 
   return (
-    <Stack.Navigator screenOptions={screenOptions}>
+    <Stack.Navigator
+      screenOptions={screenOptions}
+      UNSTABLE_routeNamesChangeBehavior="lastUnhandled"
+    >
       {renderAuthScreens({ isSignedIn, isOnboardingCompleted })}
       <Stack.Screen name="NotFound" component={NotFound} />
     </Stack.Navigator>
diff --git a/examples/react-navigation-advanced/src/navigation/screens/Explore.tsx b/examples/react-navigation-advanced/src/navigation/screens/Explore.tsx
@@ -43,8 +43,8 @@ export function Explore() {
 
           <Text style={styles.sectionHeader}>Deferred Link + Auth Gate</Text>
           <Text style={styles.bullet}>
-            Copy a Detour link, sign out, then relaunch. The link survives sign-in —{" "}
-            <Text style={styles.accent}>useDetourGate</Text> picks it up once authenticated.
+            Copy a Detour link, sign out, then relaunch. The link survives the sign-in flow — you'll
+            land on the Details screen once you complete sign-in and onboarding.
           </Text>
           <Text style={styles.bullet}>
             Make sure <Text style={styles.accent}>Copy link feature enabled</Text> is turned on in
diff --git a/examples/react-navigation-advanced/src/navigation/screens/Home.tsx b/examples/react-navigation-advanced/src/navigation/screens/Home.tsx
@@ -43,8 +43,8 @@ export function Home() {
 
           <Text style={styles.sectionHeader}>Deferred Link + Auth Gate</Text>
           <Text style={styles.bullet}>
-            Copy a Detour link, sign out, then relaunch. The link survives sign-in —{" "}
-            <Text style={styles.accent}>useDetourGate</Text> picks it up once authenticated.
+            Copy a Detour link, sign out, then relaunch. The link survives the sign-in flow — you'll
+            land on the Details screen once you complete sign-in and onboarding.
           </Text>
           <Text style={styles.bullet}>
             Make sure <Text style={styles.accent}>Copy link feature enabled</Text> is turned on in
diff --git a/examples/react-navigation-advanced/src/navigation/screens/Onboarding.tsx b/examples/react-navigation-advanced/src/navigation/screens/Onboarding.tsx
@@ -44,9 +44,8 @@ export function Onboarding() {
         <Text style={styles.sectionHeader}>Deferred Link + Auth Gate</Text>
         <Text style={styles.bullet}>
           Copy a Detour link to your clipboard, sign out, then relaunch. The deferred link will
-          survive the sign-in flow — once you authenticate,{" "}
-          <Text style={styles.accent}>useDetourGate</Text> picks it back up and navigates
-          automatically.
+          survive the sign-in flow — once you finish sign-in and onboarding, React Navigation
+          replays the link and lands you on Details automatically.
         </Text>
         <Text style={styles.bullet}>
           Make sure <Text style={styles.accent}>Copy link feature enabled</Text> is turned on in App
diff --git a/examples/react-navigation-advanced/src/navigation/screens/Settings.tsx b/examples/react-navigation-advanced/src/navigation/screens/Settings.tsx
@@ -43,8 +43,8 @@ export function Settings() {
 
           <Text style={styles.sectionHeader}>Deferred Link + Auth Gate</Text>
           <Text style={styles.bullet}>
-            Copy a Detour link, sign out, then relaunch. The link survives sign-in —{" "}
-            <Text style={styles.accent}>useDetourGate</Text> picks it up once authenticated.
+            Copy a Detour link, sign out, then relaunch. The link survives the sign-in flow — you'll
+            land on the Details screen once you complete sign-in and onboarding.
           </Text>
           <Text style={styles.bullet}>
             Make sure <Text style={styles.accent}>Copy link feature enabled</Text> is turned on in
diff --git a/examples/react-navigation-advanced/src/useDetourGate.ts b/examples/react-navigation-advanced/src/useDetourGate.ts
diff --git a/examples/react-navigation/README.md b/examples/react-navigation/README.md
@@ -15,7 +15,8 @@ This example demonstrates the minimal integration of `@swmansion/react-native-de
 - For React Navigation linking details, see:
   https://reactnavigation.org/docs/deep-linking?config=static#integrating-with-other-tools
 
-For the dedicated helper API (`useDetourReactNavigationLinking`), see `examples/react-navigation-advanced`.
+For an auth-gated setup that uses React Navigation's pending-link behavior to survive sign-in and
+onboarding, see `examples/react-navigation-advanced`.
 
 ## Test flow
 
diff --git a/packages/react-native-detour/src/index.ts b/packages/react-native-detour/src/index.ts
@@ -1,16 +1,14 @@
 export { DetourProvider, useDetourContext } from "./DetourContext";
-export { DETOUR_LINKING_PREFIX, Detour, useDetourReactNavigationLinking } from "./reactNavigation";
+export { DETOUR_LINKING_PREFIX, Detour } from "./reactNavigation";
 
 export type {
   Config,
-  DetourReactNavigationLinking,
   DetourContextType,
   DetourLink,
   DetourUrlEvent,
   DetourUrlSubscription,
   DetourStorage,
   LinkType,
-  UseDetourReactNavigationLinkingOptions,
 } from "./links/types/index";
 
 export { DetourAnalytics } from "./analytics/analytics";
diff --git a/packages/react-native-detour/src/links/types/index.ts b/packages/react-native-detour/src/links/types/index.ts
@@ -53,16 +53,3 @@ export type DetourUrlEvent = {
 export type DetourUrlSubscription = {
   remove: () => void;
 };
-
-export type DetourReactNavigationLinking<Config = unknown> = {
-  prefixes: string[];
-  config: Config;
-  getInitialURL: () => Promise<string | undefined>;
-  subscribe: (listener: (url: string) => void) => () => void;
-};
-
-export type UseDetourReactNavigationLinkingOptions<Config = unknown> = {
-  config: Config;
-  canHandleUrl?: boolean;
-  prefixes?: string[];
-};
diff --git a/packages/react-native-detour/src/reactNavigation.ts b/packages/react-native-detour/src/reactNavigation.ts
@@ -1,23 +1,11 @@
-import { useCallback, useEffect, useMemo, useRef } from "react";
-
-import type {
-  DetourReactNavigationLinking,
-  DetourUrlEvent,
-  DetourUrlSubscription,
-  UseDetourReactNavigationLinkingOptions,
-} from "./links/types/index";
+import type { DetourUrlEvent, DetourUrlSubscription } from "./links/types/index";
 import {
   DETOUR_LINKING_PREFIX,
   addReactNavigationEventListener,
   getReactNavigationInitialUrl,
 } from "./links/utils/reactNavigation";
 
-export type {
-  DetourReactNavigationLinking,
-  DetourUrlEvent,
-  DetourUrlSubscription,
-  UseDetourReactNavigationLinkingOptions,
-};
+export type { DetourUrlEvent, DetourUrlSubscription };
 
 type DetourReactNavigationApi = {
   getInitialURL: () => Promise<string | undefined>;
@@ -32,76 +20,4 @@ export const Detour: DetourReactNavigationApi = {
   addEventListener: addReactNavigationEventListener,
 };
 
-export const useDetourReactNavigationLinking = <Config>({
-  config,
-  canHandleUrl = true,
-  prefixes = [DETOUR_LINKING_PREFIX],
-}: UseDetourReactNavigationLinkingOptions<Config>): DetourReactNavigationLinking<Config> => {
-  const listenerRef = useRef<((url: string) => void) | undefined>(undefined);
-  const queuedUrlRef = useRef<string | undefined>(undefined);
-  const canHandleRef = useRef(canHandleUrl);
-  canHandleRef.current = canHandleUrl;
-
-  const emitOrQueue = useCallback((url: string) => {
-    if (canHandleRef.current && listenerRef.current) {
-      listenerRef.current(url);
-      return;
-    }
-
-    // Keep only the latest pending link while the app gate is closed.
-    queuedUrlRef.current = url;
-  }, []);
-
-  useEffect(() => {
-    if (!canHandleUrl || !listenerRef.current || !queuedUrlRef.current) {
-      return;
-    }
-
-    const queuedUrl = queuedUrlRef.current;
-    queuedUrlRef.current = undefined;
-    listenerRef.current(queuedUrl);
-  }, [canHandleUrl]);
-
-  return useMemo<DetourReactNavigationLinking<Config>>(
-    () => ({
-      prefixes,
-      config,
-      async getInitialURL() {
-        const url = await getReactNavigationInitialUrl();
-        if (!url) {
-          return undefined;
-        }
-
-        if (!canHandleRef.current) {
-          queuedUrlRef.current = url;
-          return undefined;
-        }
-
-        return url;
-      },
-      subscribe(listener) {
-        listenerRef.current = listener;
-
-        if (canHandleRef.current && queuedUrlRef.current) {
-          const queuedUrl = queuedUrlRef.current;
-          queuedUrlRef.current = undefined;
-          listener(queuedUrl);
-        }
-
-        const subscription = addReactNavigationEventListener("url", ({ url }) => {
-          emitOrQueue(url);
-        });
-
-        return () => {
-          if (listenerRef.current === listener) {
-            listenerRef.current = undefined;
-          }
-          subscription.remove();
-        };
-      },
-    }),
-    [config, emitOrQueue, prefixes],
-  );
-};
-
 export { DETOUR_LINKING_PREFIX };
