Skip to main content
Version: 2.0.0

Migration to v2

This guide covers both migration paths to @swmansion/[email protected].

Choose the right migration path
  • If your app is still on 0.x, start from From 0.x.
  • If your app is already on 1.0.1, start from From 1.0.1.

From 0.x​

Migration checklist (0.x -> 2.0.0)​

AreaIn 0.xIn 2.0.0
Config keyLegacy API_KEY form in older integrationsapiKey
Link data in contextlinkRoute / legacy fieldslink object (route, pathname, params, url, type)
Link-source controlNo explicit mode in older flows`linkProcessingMode: 'all'
Device fingerprint dependenciesreact-native-device-infoexpo-constants + expo-device
Expo Web behaviorNot explicitly guardedDetourProvider 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 SDK 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)​

AreaIn 1.0.1In 2.0.0
Device fingerprint dependenciesreact-native-device-infoexpo-constants + expo-device
Peer dependency install commandIncluded react-native-device-infoUses Expo modules only (no react-native-device-info)
Expo Web behaviorNot explicitly guardedDetourProvider is disabled on web (no-op context + one dev warning)

Update dependencies​

  1. Remove old dependency:
npm uninstall react-native-device-info
  1. 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 SDK 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​

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

We are Software Mansion.

Hire us