BlogExpo

Expo Router deep links and deferred deep links: a complete setup

· 6 min read · By the Strait team

What Expo Router does with deep links on its own, the three things it can't do (short links, installs, in-app browsers), and a step-by-step setup with app.json, +native-intent, a development build, SHA-256 fingerprints and a Google Play test for deferred links.

Expo Router makes deep linking look solved. Every file in app/ is a route, and every route can be opened by a URL. Then you share a short link in WhatsApp, someone without the app installs from the Play Store, and they land on your home screen.

This post explains what Expo Router does with links by itself, where that stops, and how to add short links and deferred deep links without fighting the router. The code is for Expo SDK 51 or newer with Expo Router (+native-intent arrived in Expo Router 3.5).

What Expo Router does on its own

Expo's documentation says that with Expo Router, "deep linking is automatically enabled for all of your app's screens" (Expo: Linking overview). With "scheme": "yourapp" in app.json, a file at app/product/[id].tsx answers yourapp://product/42, and with App Links or Universal Links set up for your website, it answers https://yourwebsite.com/product/42 too.

That covers one case well: the app is installed, and the link's path is exactly one of your routes.

The three things it can't do

Situation What Expo Router sees Result
A short link, https://hilltop.strait.link/summer The path /summer "Unmatched route": there is no app/summer.tsx
A first open after an install from the store No URL at all The home screen
A tap inside Instagram's or Facebook's browser Usually nothing: the web view loads the link itself instead of handing it to the system A web page inside that app

Short links exist because campaign links need to be short, change destination, be counted, and work for people without the app. All three need something in front of the router: a link service that knows what /summer points to, carries it through an install, and gets people out of in-app browsers.

How the pieces fit

How a link reaches an Expo Router screenThe phone opens the app with a link. The +native-intent file sends Expo Router to the first screen. The Strait SDK resolves the link, or reads the Play referrer after an install, and its onLink callback pushes the right route. Link opens the app First open after install +native-intentrouter goes to "/" SDK: resolve the short link or read the Play referrerone onLink callback for both router.push(path)
The router stays in charge of screens. The SDK only tells it which one.

The rest of this post sets that up with Strait. The full reference is the Expo (Expo Router) docs page.

Step 1: install the SDK

The Strait SDK for Expo is the same one bare React Native uses, plus two helpers: AsyncStorage (for the once-per-install flag and offline open reports) and the Play Install Referrer module (for exact Android installs). The install command is in step 1 of the Expo docs. Use npx expo install for the two helpers, so their versions match your Expo SDK.

app.json
{
  "expo": {
    "scheme": "yourapp",
    "android": {
      "package": "com.yourcompany.yourapp",
      "intentFilters": [{
        "action": "VIEW",
        "autoVerify": true,
        "data": [{ "scheme": "https", "host": "hilltop.strait.link" }],
        "category": ["BROWSABLE", "DEFAULT"]
      }]
    },
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp",
      "associatedDomains": ["applinks:hilltop.strait.link"]
    }
  }
}
  • scheme registers yourapp://, which the link server uses to hand a link from a browser to your app.
  • autoVerify is required for App Links. Expo's guide calls it out: "Specifying autoVerify is required for Android App Links to work correctly" (Expo: Android App Links).
  • associatedDomains takes the host without https://, a mistake Expo's iOS guide also warns about (Expo: iOS Universal Links). In Strait, iPhone links were tested on a real iPhone in October 2026; iPhone install matching is opt-in.

Run npx expo config --type public to confirm all three made it into the config.

Expo Router tries to route every incoming URL itself. https://hilltop.strait.link/summer isn't a screen, so you'd see "Unmatched route". Expo provides a hook for exactly this: a +native-intent file whose redirectSystemPath receives the incoming link and an initial flag that is true when the link launched the app (Expo Router: +native-intent).

app/+native-intent.tsx
// Strait's onLink (app/_layout.tsx) knows each link's real destination.
// Send Expo Router to the first screen and let onLink do the routing.
export function redirectSystemPath({ path }: { path: string; initial: boolean }) {
  // Your app's own links (a sign-in callback, say) keep the default handling.
  if (path.startsWith('yourapp://auth/')) return path;
  return '/';
}

Expo's own page notes that path is not guaranteed to be a path or even a valid URL, which is why this checks a plain string prefix instead of parsing it.

Step 4: route in the root layout

app/_layout.tsx
import { Stack, router, useRootNavigationState, type Href } from 'expo-router';
import { useEffect } from 'react';
import { links } from '../links';

export default function RootLayout() {
  const ready = useRootNavigationState()?.key;
  useEffect(() => {
    if (!ready) return;
    // Opened from a link, or first open after install: same callback.
    return links.onLink((e) => {
      if (e.matched && e.path) router.push({ pathname: e.path, params: e.params } as Href);
    });
  }, [ready]);
  return <Stack />;
}

Wait for the root navigation state before pushing, or a cold-start link can arrive before the navigator exists. onLink replays the launch link to late subscribers, so subscribing after start() loses nothing. links is the client from links.ts, created once with your publishable key and link host, the same file as in bare React Native.

The event tells you what happened: kind is direct (a link opened the app) or deferred (tapped before install), and route is app_link, custom_scheme or install_referrer on Android. When matched is false, reason says why (not_found, expired, no_match…), and the app simply stays on its first screen.

Step 5: a development build, not Expo Go

Expo's docs say "support for incoming links in Expo Go is limited" and recommend development builds for testing links. The SDK also has a native module Expo Go can't load. Build your own:

Terminal
npx expo run:android            # local build; runs prebuild for you
eas build --profile development --platform android   # or in the cloud

Then hand the app a link the way the phone would:

Terminal
adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42"

That should open app/product/[id].tsx with id 42. If it shows "Unmatched route", step 3 is missing.

For https://hilltop.strait.link/… links to open the app directly, Android has to verify the domain, and the domain's assetlinks.json must list the certificate of each build you install:

Terminal
# Local builds: the project's debug keystore
keytool -list -v -keystore android/app/debug.keystore -storepass android | grep SHA256

# EAS builds: pick the build profile; the keystore's SHA-256 is listed
eas credentials -p android

Builds installed from Google Play are re-signed with the Play App Signing key, so add that fingerprint too (Play Console, App integrity). Strait serves assetlinks.json on your link domain from the fingerprints in Dashboard → Apps & stores. Check the result with the assetlinks.json checker, and on the phone with adb shell pm get-app-links com.yourcompany.yourapp.

The deferred path can only be tested with an install from Google Play, because the link travels in the Play Install Referrer and a locally built app has none. An internal testing track is enough:

  1. Upload a build to internal testing and install it once from Play.
  2. Uninstall it.
  3. Tap https://hilltop.strait.link/summer on the phone. Google Play opens.
  4. Install from Play and open the app.

The first screen should be the link's screen, and the event should have kind: 'deferred' and route: 'install_referrer'. We ran this test on a real phone with an internal testing build of our own React Native test app (the same SDK Expo uses), and the first open landed on the link's screen. The whole flow is in Test deep links in React Native, and the theory in deferred deep linking explained.

Before tapping for real, the Will it open my app? simulator shows where a tap from WhatsApp, Instagram or Chrome would go with the app installed or not.

Common errors

Symptom Cause
Links open Expo Go, or nothing You're in Expo Go. Use a development build
"Unmatched route" after a tap app/+native-intent.tsx is missing or returns path for your link domain
The screen opens twice Your link domain is handled by both the router and onLink
Works locally, not from EAS The EAS keystore's SHA-256 isn't in Settings
Deferred test opens the home screen The app wasn't installed from Google Play

Sources and how we checked

  • Expo docs: Linking overview, Android App Links, iOS Universal Links and +native-intent. Quotes checked in October 2026.
  • The SDK calls, event fields and setup are from the Strait React Native SDK and its Expo docs page.
  • The deferred result is from our real-phone test with a Google Play internal testing build of our React Native test app (October 2026). We have not run that test with an Expo-built app.