feat: add custom native intent for expo router (#36)

Author: piaccho

.github/workflows/ci.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Build package
         run: yarn prepare
 
-  build-web:
+  smoke-mobile:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -59,6 +59,6 @@ jobs:
       - name: Setup
         uses: ./.github/actions/setup
 
-      - name: Build example for Web
+      - name: Smoke build mobile example
         run: |
-          yarn example expo export --platform web
+          CI=1 yarn workspace @swmansion/react-native-detour-expo-router-native-intent expo export --platform ios --platform android

.gitignore

@@ -41,13 +41,6 @@ project.xcworkspace
 local.properties
 android.iml
 
-# Cocoapods
-#
-example/ios/Pods
-
-# Ruby
-example/vendor/
-
 # node.js
 #
 node_modules/

CONTRIBUTING.md

@@ -9,7 +9,7 @@ We want this community to be friendly and respectful to each other. Please follo
 This project is a monorepo managed using [Yarn workspaces](https://yarnpkg.com/features/workspaces). It contains the following packages:
 
 - The library package in the root directory.
-- An example app in the `example/` directory.
+- Example apps in the `examples/` directory.
 
 To get started with the project, make sure you have the correct version of [Node.js](https://nodejs.org/) installed. See the [`.nvmrc`](./.nvmrc) file for the version used in this project.
 
@@ -21,7 +21,7 @@ yarn
 
 > Since the project relies on Yarn workspaces, you cannot use [`npm`](https://github.com/npm/cli) for development without manually migrating.
 
-The [example app](/example/) demonstrates usage of the library. You need to run it to test any changes you make.
+The [bare example app](/examples/expo-bare/) demonstrates usage of the library. You need to run it to test any changes you make.
 
 It is configured to use the local version of the library, so any changes you make to the library's source code will be reflected in the example app. Changes to the library's JavaScript code will be reflected in the example app without a rebuild, but native code changes will require a rebuild of the example app.
 
@@ -30,19 +30,19 @@ You can use various commands from the root directory to work with the project.
 To start the packager:
 
 ```sh
-yarn example start
+yarn examples:expo-bare start
 ```
 
 To run the example app on Android:
 
 ```sh
-yarn example android
+yarn examples:expo-bare android
 ```
 
 To run the example app on iOS:
 
 ```sh
-yarn example ios
+yarn examples:expo-bare ios
 ```
 
 To confirm that the app is running with the new architecture, you can check the Metro logs for a message like this:
@@ -56,7 +56,7 @@ Note the `"fabric":true` and `"concurrentRoot":true` properties.
 To run the example app on Web:
 
 ```sh
-yarn example web
+yarn examples:expo-bare web
 ```
 
 Make sure your code passes TypeScript and ESLint. Run the following to verify:
@@ -117,9 +117,9 @@ The `package.json` file contains various scripts for common tasks:
 - `yarn typecheck`: type-check files with TypeScript.
 - `yarn lint`: lint files with ESLint.
 - `yarn test`: run unit tests with Jest.
-- `yarn example start`: start the Metro server for the example app.
-- `yarn example android`: run the example app on Android.
-- `yarn example ios`: run the example app on iOS.
+- `yarn examples:expo-bare start`: start the Metro server for the bare example app.
+- `yarn examples:expo-bare android`: run the bare example app on Android.
+- `yarn examples:expo-bare ios`: run the bare example app on iOS.
 
 ### Sending a pull request
 

README.md

@@ -6,7 +6,7 @@ SDK for handling deferred links in React Native.
 
 ## Create an account
 
-You need a Detour account to generate app credentials and configure your links.
+You need a Detour account to generate app credentials and configure your links.  
 Sign up here: [https://godetour.dev/auth/signup](https://godetour.dev/auth/signup)
 
 ## Quick links
@@ -42,7 +42,7 @@ npm install expo-localization react-native-device-info expo-clipboard @react-nat
 import { DetourProvider, type Config } from '@swmansion/react-native-detour';
 
 const config: Config = {
-  API_KEY: '<REPLACE_WITH_YOUR_API_KEY>',
+  apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
   appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
   shouldUseClipboard: true,
 };
@@ -61,34 +61,86 @@ export default function RootLayout() {
 ```js
 import { useDetourContext } from '@swmansion/react-native-detour';
 import * as SplashScreen from 'expo-splash-screen';
-import { Redirect, Stack } from 'expo-router';
+import { Stack, usePathname, useRouter } from 'expo-router';
 
 SplashScreen.preventAutoHideAsync();
 
 export function RootNavigator() {
   const { isLinkProcessed, linkRoute, clearLink } = useDetourContext();
+  const pathname = usePathname();
+  const router = useRouter();
 
   useEffect(() => {
     if (isLinkProcessed) {
       SplashScreen.hide();
     }
   }, [isLinkProcessed]);
 
+  useEffect(() => {
+    if (!isLinkProcessed || !linkRoute) return;
+    if (pathname !== linkRoute) {
+      router.replace(linkRoute);
+      return;
+    }
+    clearLink(); // avoid redirecting again when returning to this screen
+  }, [clearLink, isLinkProcessed, linkRoute, pathname, router]);
+
   if (!isLinkProcessed) {
     return null;
   }
 
-  if (linkRoute) {
-    clearLink(); // avoid redirecting again when returning to this screen
-    return <Redirect href={linkRoute} />;
-  }
-
   return <Stack />;
 }
 ```
 
 Learn more about usage from our [docs](https://docs.swmansion.com/detour/docs/SDK/sdk-usage)
 
+### Controlling which links Detour processes
+
+Use `linkProcessingMode` to control which link sources the SDK listens to:
+
+|Value|Universal/App links|Deferred links|Custom scheme links|
+|---|---|---|---|
+|`'all'` (default)|✅|✅|✅|
+|`'web-only'`|✅|✅|❌|
+|`'deferred-only'`|❌|✅|❌|
+
+```js
+const config: Config = {
+  apiKey: '<REPLACE_WITH_YOUR_API_KEY>',
+  appID: '<REPLACE_WITH_APP_ID_FROM_PLATFORM>',
+  // Process Universal/App links and deferred links, but let your own
+  // navigation layer handle custom scheme links (e.g. myapp://...).
+  linkProcessingMode: 'web-only',
+};
+```
+
+Use `'deferred-only'` when Expo Router's `+native-intent.tsx` handler is already resolving runtime Universal/App links — this prevents double-processing.
+
+## Examples
+
+All example apps with Detour SDK integrated live in `examples/`:
+
+- `examples/expo-bare`
+- `examples/expo-router`
+- `examples/expo-router-native-intent`
+- `examples/expo-router-advanced`
+- `examples/react-navigation`
+- `examples/react-navigation-advanced`
+
+You can run them from repo root:
+
+```sh
+yarn examples:expo-bare start
+yarn examples:expo-router start
+yarn examples:expo-router-native-intent start
+yarn examples:expo-router-advanced start
+yarn examples:react-navigation start
+yarn examples:react-navigation-advanced start
+```
+
+If you want to know more details about a given example and how to configure it, please read the README in the appropriate example directory.
+
 ## Clearing handled links
 
 If your app redirects based on `linkRoute` (especially in entry screens), call `clearLink()` after handling the route. This prevents repeated redirects when the user returns to the same screen.
@@ -111,7 +163,7 @@ export type Config = {
   /**
    * Your API key from the Detour dashboard.
    */
-  API_KEY: string;
+  apiKey: string;
 
   /**
    * Optional: A flag to determine if the provider should check the clipboard for a deferred link.
@@ -121,6 +173,15 @@ export type Config = {
    */
   shouldUseClipboard?: boolean;
 
+  /**
+   * Optional: Controls which link sources are handled by the SDK.
+   * - 'all': deferred links + Universal/App links + custom scheme links (default)
+   * - 'web-only': deferred links + Universal/App links, but NOT custom scheme links
+   * - 'deferred-only': only deferred links (use when native-intent already handles runtime links)
+   * Defaults to 'all'.
+   */
+  linkProcessingMode?: 'all' | 'web-only' | 'deferred-only';
+
   /**
    * Optional: A custom storage adapter. Defaults to AsyncStorage if not provided.
    */
@@ -135,23 +196,25 @@ This type represents the object returned by the useDetourContext hook, containin
 ```js
 export type DetourContextType = {
   /**
-   * Boolean indicating if the deferred link, Universal/App Link or scheme deep link has been processed.
-   * This is useful for conditionally rendering UI components.
+   * Boolean indicating if the initial link (deferred, Universal/App Link, or scheme) has been processed.
+   * Use this to gate navigation or hide the splash screen.
    */
   isLinkProcessed: boolean;
 
   /**
-   * The deferred link, Universal/App Link or scheme deep link url. This can be a string or a URL object, or null if no link was found.
+   * The raw link URL (string or URL object), or null if no link was found.
    */
   linkUrl: string | URL | null;
 
   /**
-   * The detected route based on the link url, or null if no route was detected.
+   * The parsed route path derived from the link (e.g. '/details/42'), or null if no link was found.
    */
   linkRoute: string | null;
 
   /**
-   * The type of the detected link. Can be 'deferred', 'verified' or 'scheme'. This can be null if no link was found.
+   * The type of the detected link: 'deferred', 'verified' (Universal/App link), or 'scheme'.
+   * 'scheme' is only emitted when linkProcessingMode is 'all' (default).
+   * Null if no link was found.
    */
   linkType: LinkType | null;