Migration to v2

This guide covers both migration paths to @swmansion/react-native-detour@2.0.0.

From 0.x

Migration checklist (`0.x` -> `2.0.0`)

Area	In `0.x`	In `2.0.0`
Config key	Legacy `API_KEY` form in older integrations	`apiKey`
Link data in context	`linkRoute` / legacy fields	`link` object (`route`, `pathname`, `params`, `url`, `type`)
Link-source control	No explicit mode in older flows	`linkProcessingMode: 'all' \| 'web-only' \| 'deferred-only'`
Device fingerprint dependencies	`react-native-device-info`	`expo-constants` + `expo-device`
Expo Web behavior	Not explicitly guarded	`DetourProvider` disabled on web (no-op context)

1. Update dependencies

Remove old dependency:

npm uninstall react-native-device-info

Install current peer dependencies:

npm install expo-localization expo-clipboard expo-constants expo-device @react-native-async-storage/async-storage expo-application

If you use Yarn/PNPM/Bun, use equivalent commands from Installation.

2. Update config shape

// before (legacy)
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,
  linkProcessingMode: 'all',
};

3. Update context usage

// before (legacy route string)
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();
}

4. Choose `linkProcessingMode`

'all' (default) — deferred + Universal/App + scheme links
'web-only' — deferred + Universal/App links, no scheme links
'deferred-only' — deferred only (recommended if Expo Router +native-intent.tsx handles runtime links)

From 1.0.1

Migration checklist (`1.0.1` -> `2.0.0`)

Area	In `1.0.1`	In `2.0.0`
Device fingerprint dependencies	`react-native-device-info`	`expo-constants` + `expo-device`
Peer dependency install command	Included `react-native-device-info`	Uses Expo modules only (no `react-native-device-info`)
Expo Web behavior	Not explicitly guarded	`DetourProvider` is disabled on web (no-op context + one dev warning)

Update dependencies

Remove old dependency:
Terminal window
```
npm uninstall react-native-device-info
```

Install current peer dependencies:

npm install expo-localization expo-clipboard expo-constants expo-device @react-native-async-storage/async-storage expo-application

If you use Yarn/PNPM/Bun, use equivalent commands from Installation.

Web behavior update

In 2.0.0, DetourProvider does not initialize on Expo Web. Returned context on web:

isLinkProcessed: true
link: null
clearLink: () => {}

This prevents partial/unsupported initialization on web while keeping app tree stable.

Shared validation checklist

iOS/Android deferred flow still resolves route and parameters.
Runtime Universal/App Links still resolve according to linkProcessingMode.
Expo Web no longer attempts Detour processing and app still renders without provider runtime errors.
Exactly one DetourProvider is mounted in app root.