Menu
Set up and test universal links for iOS using setup-safari
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | universal-links |
| description | Set up and test universal links for iOS using setup-safari |
Use bunx setup-safari to configure and test universal links (deep links) on iOS.
Universal links with custom domains require custom native builds. Your app will no longer work in Expo Go.
However, for basic deep linking during development:
exp:// URL scheme and Expo-hosted URLsIf you only need deep linking for development/testing, try npx expo start with Expo Go first. Only create custom builds when you need production universal links with your own domain.
Run setup-safari with your Apple ID to automate credential lookup:
EXPO_APPLE_ID="your-apple-id@email.com" bunx setup-safari
This will:
After running, you must manually:
Create public/.well-known/apple-app-site-association (no file extension):
{
"applinks": {
"details": [
{
"appIDs": ["TEAM_ID.com.your.bundleid"],
"components": [
{
"/": "*",
"comment": "Matches all routes"
}
]
}
]
},
"activitycontinuation": {
"apps": ["TEAM_ID.com.your.bundleid"]
},
"webcredentials": {
"apps": ["TEAM_ID.com.your.bundleid"]
}
}
import { ScrollViewStyleReset } from "expo-router/html";
export default function Root({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta httpEquiv="X-UA-Compatible" content="IE=edge" />
<meta
name="viewport"
content="width=device-width, initial-scale=1, shrink-to-fit=no"
/>
<meta name="apple-itunes-app" content="app-id=YOUR_ITUNES_ID" />
<ScrollViewStyleReset />
</head>
<body>{children}</body>
</html>
);
}
{
"expo": {
"ios": {
"associatedDomains": [
"applinks:yourdomain.com",
"activitycontinuation:yourdomain.com",
"webcredentials:yourdomain.com"
]
}
}
}
# Deploy web (AASA file must be accessible)
npx expo export -p web && npx eas-cli deploy
# Rebuild iOS app with new entitlements
npx expo run:ios
# Or for TestFlight: npx testflight
For interactive mode (requires TTY):
bunx setup-safari
Universal links require two parts:
Host at https://yourdomain.com/.well-known/apple-app-site-association:
{
"applinks": {
"apps": [],
"details": [
{
"appID": "TEAM_ID.com.example.app",
"paths": ["*"]
}
]
}
}
Path patterns:
* - Match all paths/products/* - Match paths starting with /products//item/??? - Match exactly 3 characters after /item/NOT /admin/* - Exclude pathsIn your app.json or app.config.js:
{
"expo": {
"ios": {
"associatedDomains": [
"applinks:yourdomain.com",
"applinks:www.yourdomain.com"
]
}
}
}
After setup, test with setup-safari:
npx setup-safari
Or manually test in Safari:
Test universal links without deploying a website using Expo's tunnel feature:
export EXPO_TUNNEL_SUBDOMAIN=my-app-name
{
"expo": {
"ios": {
"associatedDomains": ["applinks:my-app-name.ngrok.io"]
}
}
}
npx expo run:ios
npx expo start --tunnel
https://my-app-name.ngrok.io in Safari on your device. It should open your app directly.The tunnel creates a public HTTPS URL that serves the AASA file automatically, letting you test the full universal links flow during development.
Check if Apple has cached your AASA:
curl "https://app-site-association.cdn-apple.com/a/v1/yourdomain.com"
Validate AASA file format:
curl https://yourdomain.com/.well-known/apple-app-site-association | jq
Common issues:
Content-Type: application/jsonWith Expo Router, handle incoming links automatically:
// app/[...path].tsx handles all deep link paths
// app/products/[id].tsx handles /products/:id links
Access link parameters:
import { useLocalSearchParams } from "expo-router";
export default function Product() {
const { id } = useLocalSearchParams();
return <Text>Product: {id}</Text>;
}