# Add Universal Links to an Expo App

Yes. An agent adds iOS universal links and Android App Links to your Expo app: app.json entitlements, well-known files, https prefixes, a Jest test and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-universal-links/expo/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how navigation and linking are set up now. In an app generated from infinitered/ignite's boilerplate, `app.json` sets `scheme` to `helloworld`, `ios.bundleIdentifier` and `android.package` to `com.helloworld`, `newArchEnabled` and `plugins` for `expo-localization`, `expo-font`, `expo-splash-screen`, `react-native-edge-to-edge` and `expo-build-properties`; `app.config.ts` spreads that config and adds an iOS privacy manifest. `package.json` pins `expo 55.0.5`, `expo-linking ~55.0.7`, `@react-navigation/native ^7.0.14`, `native-stack` and `bottom-tabs` 7, `jest-expo ~55.0.9` and `@testing-library/react-native`. There are no `ios/` or `android/` directories, so native config comes from `app.json` and a prebuild, and `eas.json` has `development`, `preview` and `production` profiles.

Linking already exists for the custom scheme only. `app/app.tsx` builds `prefix` with `Linking.createURL("/")` from `expo-linking` and a `config` that maps `Login` to the empty path, `Welcome` to `welcome`, and the `Demo` tab navigator's screens to `showroom/:queryIndex?/:itemIndex?`, `debug`, `podcast` and `community`, then passes `{ prefixes: [prefix], config }` to `AppNavigator`, whose `NavigationContainer` receives it. `app/navigators/navigationUtilities.ts` already checks `Linking.getInitialURL()` and skips restoring persisted navigation state when the app opened from a link, so that part needs no change. The param types in `navigationTypes.ts` give `DemoShowroom` optional `queryIndex` and `itemIndex`.

The agent adds the https side. In `app.json` it adds `ios.associatedDomains` with `applinks:<your domain>` and an `android.intentFilters` entry with `action` `VIEW`, `autoVerify` true, `data` of scheme `https`, the host and a `pathPrefix` of `/`, and categories `BROWSABLE` and `DEFAULT`. In `app.tsx` it adds `https://<your domain>` to `prefixes` beside the scheme prefix so the same `config` serves both. It writes the two files the domain must serve: `.well-known/apple-app-site-association` with the `applinks` details for the Team ID and `com.helloworld`, and `.well-known/assetlinks.json` with `delegate_permission/common.handle_all_urls`, `android_app`, the package name and a `sha256_cert_fingerprints` placeholder. They go in a `web/.well-known/` folder in the repository with a README line saying they are served from the website over HTTPS as `application/json`, since the app itself does not host them. The Team ID and the fingerprint from `eas credentials -p android` are left as marked placeholders the reviewer fills in.

The one thing testable without a device is the path mapping, so the agent moves `config` out of `app.tsx` into `app/navigators/linking.ts` and adds `test/linking.test.ts` under the existing `jest-expo` preset with `test/setup.ts`: `getStateFromPath` from `@react-navigation/native` turns `/showroom/2/3` into a `Demo` route with `DemoShowroom` and params `queryIndex: "2"`, `itemIndex: "3"`, `/podcast` into `DemoPodcastList`, and `/welcome` into `Welcome`; `getPathFromState` round-trips them. It runs `pnpm test`, `pnpm compile` (`tsc --noEmit`) and `pnpm lint:check`, and `npx expo config --type introspect` to show the resolved `associatedDomains` and `intentFilters`, and pastes all four. A new native build is needed for the entitlement to exist, which the pull request says.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add universal links (iOS) and App Links (Android) to this Expo app for the domain https://links.example.com and open a pull request. Read app.json, app.config.ts, eas.json, package.json, app/app.tsx, app/navigators/AppNavigator.tsx, navigationUtilities.ts and navigationTypes.ts first. Add ios.associatedDomains with applinks:links.example.com and an android.intentFilters entry with action VIEW, autoVerify true, data scheme https, host links.example.com and pathPrefix /, categories BROWSABLE and DEFAULT. Add https://links.example.com to the linking prefixes beside the existing scheme prefix, keeping the current screen config. Move the linking config into app/navigators/linking.ts and add a Jest test that uses getStateFromPath and getPathFromState from @react-navigation/native to check /showroom/2/3, /podcast and /welcome map to the right screens and params. Write web/.well-known/apple-app-site-association and web/.well-known/assetlinks.json with marked placeholders for the Apple Team ID and the Android SHA-256 fingerprint, and a README note on serving them over HTTPS. Run pnpm test, pnpm compile, pnpm lint:check and npx expo config --type introspect, and paste the output. Do not add Expo Router and do not run a native build.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with `ios.associatedDomains` and `android.intentFilters` in `app.json`, a new `app/navigators/linking.ts` holding the prefixes and screen config, a shorter `app/app.tsx` that imports it, `test/linking.test.ts`, and `web/.well-known/apple-app-site-association` and `assetlinks.json` with two marked placeholders. The description shows the resolved config from `expo config --type introspect`, the Jest, `tsc` and ESLint output, and the two values the reviewer must supply.

The boilerplate has no CI workflow in the repository, so the pasted output is the check; a team that runs `pnpm test` and `pnpm compile` in a workflow sees them on the pull request.

A reviewer fills in the Team ID and the fingerprint, puts the two files on the domain, then runs an EAS build with the `development` profile so the entitlement and intent filter exist in the binary, and opens `https://links.example.com/podcast` on a device. On Android, `adb shell am start -a android.intent.action.VIEW -d <url> com.helloworld` does the same from a terminal.

## Run it on every new app from the boilerplate

A studio that starts apps from the boilerplate sends one `POST /o/{org}/sessions` per new repository with this prompt and that repository in `resources`, each with its own domain in the prompt. Each run reads its own `app.json` and screen config, so an app that already renamed its scheme or screens gets a matching path map, and each opens its own pull request. One repository per run; a `request_id` in the body makes a retry safe.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request and its two placeholders from.

## Why run it on Rush?

Universal links fail silently: a missing `autoVerify`, a wrong `pathPrefix` or a path map that does not match the navigator sends the user to the browser with no error anywhere. In a Rush sandbox the agent checks the one part that can be checked without a device, the mapping from URL to navigation state, with React Navigation's own `getStateFromPath`, and resolves the final Expo config, keeping both outputs in the run's record beside the diff.

The rest is configuration spread across `app.json`, the navigator, two JSON files for the website and a build profile, which is exactly the kind of change a laptop session does half of. The agent does the whole pass, marks the two values only the team has, and the same request works unchanged on the next app from the boilerplate.

## Frequently asked questions

### Why not switch to Expo Router?

Because the app uses React Navigation 7 with a native stack and a tab navigator, and its `linking` config already maps paths to screens. Adding https prefixes to that config is a small change; a router migration is a different job and is left out on purpose.

### What do I still have to do by hand?

Supply the Apple Team ID and the Android signing certificate's SHA-256 fingerprint (`eas credentials -p android` prints it), serve the two `.well-known` files from the domain over HTTPS as `application/json`, and make a new native build. The entitlement and intent filter live in the binary, so an existing build will not open the links.

### Does the custom scheme stop working?

No. The `helloworld` scheme prefix stays first in `prefixes` and the https prefix is added beside it, so `helloworld://podcast` and `https://links.example.com/podcast` reach the same screen through the same config.

### How is the path mapping tested?

With `getStateFromPath` and `getPathFromState` from `@react-navigation/native`, the functions the `NavigationContainer` uses, under the `jest-expo` preset the project already has. The test checks that `/showroom/2/3` yields the `Demo` route, `DemoShowroom` screen and both params, and round-trips back to the same path.

## More Expo jobs

- [Migrate an Expo Project from Jest to Vitest](https://getrush.ai/run/migrate-jest-to-vitest/expo/)
- [Migrate an Expo App from React Navigation to Expo Router](https://getrush.ai/run/migrate-to-expo-router/expo/)
- [Write Component Tests for an Expo App](https://getrush.ai/run/write-component-tests/expo/)

## More jobs like this: Hand off a long task

- [Add an Unsaved Changes Guard to an Angular App](https://getrush.ai/run/add-unsaved-changes-guard/angular/)
- [Add User Registration to a CodeIgniter App](https://getrush.ai/run/add-user-registration/codeigniter/)
- [Add User Registration to a Fastify App](https://getrush.ai/run/add-user-registration/fastify/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
