Migration to v1

This guide helps migrate from older RN SDK integration patterns to @swmansion/react-native-detour@1.0.1.

Migration checklist

Area	Before	In 1.0.1
Config key	API_KEY	apiKey
Context shape	linkRoute, linkUrl, linkType exposed directly	link object (route, pathname, params, url, type)
Navigation mapping	Parse route string manually	Prefer link.pathname and link.params
Link-source control	No explicit mode	linkProcessingMode: 'all' | 'web-only' | 'deferred-only'
Expo Router native intent	Custom handler only	Optional createDetourNativeIntentHandler from @swmansion/react-native-detour/expo-router
Analytics import	legacy package/import variants	DetourAnalytics from @swmansion/react-native-detour

Config update

// before
const config = {
  API_KEY: process.env.EXPO_PUBLIC_DETOUR_API_KEY,
  appID: process.env.EXPO_PUBLIC_DETOUR_APP_ID,
};

// after
const config = {
  apiKey: process.env.EXPO_PUBLIC_DETOUR_API_KEY,
  appID: process.env.EXPO_PUBLIC_DETOUR_APP_ID,
};

Context update (linkRoute -> link)

// before
const { isLinkProcessed, linkRoute, clearLink } = useDetourContext();
if (isLinkProcessed && linkRoute) {
  router.replace(linkRoute);
  clearLink();
}

// after
const { isLinkProcessed, link, clearLink } = useDetourContext();
if (isLinkProcessed && link) {
  router.replace({ pathname: link.pathname, params: link.params });
  clearLink();
}

Decide linkProcessingMode

• Keep default 'all' when SDK should process deferred + web links + custom schemes.
• Use 'web-only' when your app handles custom schemes separately.
• Use 'deferred-only' when Expo Router native-intent flow already handles runtime/initial URLs.

Expo Router native-intent migration (optional)

If your app uses Expo Router +native-intent.tsx, there are two potential link-processing layers:

• Expo Router redirectSystemPath (before route resolution)
• Detour runtime processing in DetourProvider / useDetourContext()

Without explicit coordination, the same URL can be processed twice, or users can briefly land on an intermediate/unknown route before the final Detour route is resolved.

createDetourNativeIntentHandler is a helper that gives you a deterministic pre-routing step for Detour links. It can:

• match Detour hosts
• resolve short links using apiKey + appID
• map the resolved URL to a final Expo Router route
• return a safe fallbackPath when resolution fails/timeouts

Recommended setup

1. Add createDetourNativeIntentHandler in app/+native-intent.tsx.
2. Set linkProcessingMode: 'deferred-only' in DetourProvider so runtime/initial web links are not processed twice.
3. Keep DetourProvider mounted for deferred matching and analytics.

app/+native-intent.tsx

import { createDetourNativeIntentHandler } from '@swmansion/react-native-detour/expo-router';

export const redirectSystemPath = createDetourNativeIntentHandler({
  fallbackPath: '',
  config: {
    apiKey: process.env.EXPO_PUBLIC_DETOUR_API_KEY!,
    appID: process.env.EXPO_PUBLIC_DETOUR_APP_ID!,
    timeoutMs: 1200,
  },
});

// app/_layout.tsx
const config = {
  apiKey: process.env.EXPO_PUBLIC_DETOUR_API_KEY!,
  appID: process.env.EXPO_PUBLIC_DETOUR_APP_ID!,
  linkProcessingMode: 'deferred-only',
};

If you need custom path shaping (for example dropping app-hash segment), use the handler mapToRoute callback.

Related resources

• Usage: Expo Router native intent helper
• Examples (expo-router-native-intent, expo-router-advanced)
• Expo Router docs: Customizing links with +native-intent

Validate after migration

1. Trigger deferred link on fresh install and confirm link?.type === 'deferred'.
2. Trigger runtime Universal/App Link and confirm link?.type === 'verified'.
3. Trigger custom scheme link and confirm expected behavior for selected linkProcessingMode.
4. Confirm only one DetourProvider is mounted.