# Add Deep Links to a React Native App

Yes. An agent adds a URL scheme and universal links to your React Native app: React Navigation linking, Android intent filters, iOS URL types and tests, in a PR.

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

## What the agent does

The agent clones the app into its own cloud sandbox and reads the navigation layer before it touches a manifest. In a bare React Native app like the `template/` in thecodingmachine/react-native-boilerplate, `package.json` pins `react-native` 0.84.0 with `@react-navigation/native` ^7.1.16 and `@react-navigation/stack` ^7.4.4, scripts run `jest`, `eslint .`, `prettier --check` and `tsc`, and `engines` asks for Node 22.11 or newer. `src/navigation/Application.tsx` builds one `NavigationContainer` with a `Stack.Navigator` of two screens, `Startup` and `Example`; `src/navigation/paths.ts` names them in a `Paths` enum and `src/navigation/types.ts` gives both `undefined` params in `RootStackParamList`. Nothing passes a `linking` prop, `android/app/src/main/AndroidManifest.xml` has a single `MAIN`/`LAUNCHER` intent filter on `MainActivity`, and `ios/Boilerplate/Info.plist` declares no `CFBundleURLTypes`, so today no URL can open the app.

The JavaScript side comes first. The agent adds `src/navigation/linking.ts` exporting a `LinkingOptions<RootStackParamList>` with the custom scheme from the prompt and the https domain as `prefixes`, and a `config.screens` map that ties `Paths.Example` to a path such as `example/:id?` and `Paths.Startup` to the root. It widens `RootStackParamList` so `Example` accepts an optional `id`, reads it in `Example.tsx` through the typed `RootScreenProps`, and passes `linking` into the `NavigationContainer` in `Application.tsx`. One existing behaviour needs care: `Startup.tsx` runs a `useQuery` and then calls `navigation.reset` to `Example` on success, which would throw away a route that arrived by link on a cold start. The agent makes that reset conditional, skipping it when the navigator already has a deeper route from the initial URL, and explains the change in the pull request.

Native configuration follows. In `AndroidManifest.xml` the agent adds a second `intent-filter` on `MainActivity` with `android.intent.action.VIEW`, the `DEFAULT` and `BROWSABLE` categories and a `data` element for the scheme, and a third with `android:autoVerify="true"` for the https host so Android can treat it as an App Link once an `assetlinks.json` is served; `launchMode` is already `singleTask`, which is what React Navigation expects. In `Info.plist` it adds `CFBundleURLTypes` with the scheme, and in `ios/Boilerplate/AppDelegade.swift`, which today only starts `RCTReactNativeFactory`, it adds the `application(_:open:options:)` and `application(_:continue:restorationHandler:)` methods that hand URLs and universal-link activities to `RCTLinkingManager`. The associated-domains entitlement and the `apple-app-site-association` and `assetlinks.json` files are written as templates with the bundle identifier and package name read from the project, since the agent can write them but cannot host them.

Tests follow the suite that exists. `jest.config.js` already uses the `react-native` preset and lets `@react-navigation` through `transformIgnorePatterns`, and `src/tests/TestAppWrapper.tsx` provides the query client, theme and translations that `Example.test.tsx` renders with. The agent adds `src/navigation/linking.test.ts`, which calls `getStateFromPath` from `@react-navigation/native` with the new config and asserts that `example/42` yields the `Example` route with `id` set, that an unknown path falls back cleanly, and that a URL with the https prefix resolves the same as the scheme. It then runs `yarn lint`, which chains the ESLint flat config in `eslint.config.mjs` with its strict type-checked rules, `prettier --check` and `tsc`, and `yarn test`, the same four commands `.github/workflows/boilerplate-checks.yml` runs.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add deep linking to this React Native app with React Navigation. Read package.json, src/App.tsx, src/navigation/*, src/screens/*, android/app/src/main/AndroidManifest.xml, ios/*/Info.plist, ios/*/AppDelegate*.swift, jest.config.js and src/tests/* first. Add src/navigation/linking.ts with a LinkingOptions config using the scheme yourapp:// and https://app.example.com as prefixes, map the Example screen to example/:id? and the Startup screen to the root, type the id param in RootStackParamList and read it in Example, and pass linking to NavigationContainer. Make the Startup screen's navigation.reset skip when a deeper route arrived from a link. Add VIEW intent filters for the scheme and an autoVerify filter for the https host in AndroidManifest.xml, CFBundleURLTypes in Info.plist, and the open-URL and continue-user-activity handlers in the AppDelegate via RCTLinkingManager. Write apple-app-site-association and assetlinks.json templates under docs/ with the real bundle id and package name. Add a Jest test that checks getStateFromPath against the config. Run yarn lint and yarn test, and open a pull request listing every file, the URL patterns, the commands to open a link on a simulator and emulator, and the test output.",
  "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 on its own branch that adds `src/navigation/linking.ts` and `linking.test.ts`, changes `Application.tsx`, `types.ts`, `Startup.tsx` and `Example.tsx`, adds the intent filters to `AndroidManifest.xml`, the URL types to `Info.plist` and the two handlers to the `AppDelegate`, and places the two well-known files under `docs/` with a note on where to host them. No dependency is added: `@react-navigation/native` already exports everything the linking config and the test need.

The description lists each URL pattern and the screen it opens, the `adb shell am start` and `xcrun simctl openurl` commands to try them on an emulator and a simulator, and the `yarn lint` and `yarn test` summaries. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps every command and its output, so a reviewer can read the ESLint, Prettier, `tsc` and Jest results instead of trusting a sentence that says they passed.

Before merging, a reviewer checks that the scheme and host match what the backend and marketing pages will emit, that `autoVerify` is only on the https filter, and that the `Startup` change does not skip the reset for an ordinary launch. A follow-up on the same session can add a second screen to the config or wire `getInitialURL` to a push-notification payload.

## Run it on every new shareable screen

A team that ships several apps from the same boilerplate runs this once per repository. From a script, send the body above to `POST /o/{org}/sessions` with each repository in `resources`, one run per repository, and a `request_id` that is a UUID v5 of the repository name so a retry is safe. Give the key a `webhook_url` and every run the key starts posts `run.completed` with `data.session_url` when its turn ends; a handler reads the pull request link from the session.

Once linking exists, add an automation to the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and a prompt that checks whether a pull request adding a screen under `src/screens` also adds a path in `linking.ts` and a `getStateFromPath` case for it. The trigger clones the pull request's branch and places the event after the prompt, and the automation starts at most `max_runs_per_hour` runs in an hour.

## Why run it on Rush?

Deep linking touches four places that are usually edited by different people: the navigator, the Android manifest, the iOS plist and app delegate, and the hosted verification files. Getting them to agree on one scheme and one host is the whole job, and a mismatch only shows up on a device. The agent reads the actual `Paths`, bundle identifier and package name in its own sandbox and writes all four from the same values, then proves the JavaScript half with a test that runs without a device.

Every `yarn lint` and `yarn test` and its output stay in the run's transcript, so the pull request's claim that the strict ESLint config and the type check still pass is checkable, and the laptop that handed off the task is free while it happens. Several apps can get the same linking setup at once, each in its own sandbox and its own pull request.

## Frequently asked questions

### Custom scheme or universal links?

Both, and they share one config. The scheme (`yourapp://`) opens the app from anywhere but any app can claim it; universal links on iOS and App Links on Android open `https://` URLs only after the host serves `apple-app-site-association` and `assetlinks.json`. The agent writes both files with the real identifiers and adds the https prefix to `linking.ts`, but you host the files and add the associated-domains entitlement in Xcode.

### What happens to the Startup screen's reset?

Today `Startup.tsx` resets the stack to `Example` as soon as its query succeeds, which would discard a route that a link set on a cold start. The agent keeps the reset for a normal launch and skips it when the navigator already holds a deeper route from the initial URL, so a link to `example/42` lands on that item and an ordinary open still ends on `Example`.

### Does this work with Expo Router?

This page is for a bare React Native app with React Navigation, like the boilerplate. Expo Router derives links from the file tree and reads the scheme from `app.json`, so the same job on an Expo app edits different files; the agent reads `package.json` and `app.json` first and follows whichever setup the repository has.

### How do I try a link without a release build?

The pull request lists the commands: `adb shell am start -W -a android.intent.action.VIEW -d "yourapp://example/42"` for an emulator and `xcrun simctl openurl booted "yourapp://example/42"` for a simulator. The `getStateFromPath` test covers the mapping itself, so the device check is only for the native registration.

### Will it add any dependency?

No. `LinkingOptions` and `getStateFromPath` come from `@react-navigation/native`, which the app already has, and the native changes are plain manifest, plist and Swift edits. The ESLint config in `eslint.config.mjs` and `tsc` run over the new files unchanged.

## More React Native jobs

- [Set Up GitHub Actions CI for a React Native App](https://getrush.ai/run/add-github-actions-ci/react-native/)
- [Add Offline Support to a React Native App](https://getrush.ai/run/add-offline-support/react-native/)
- [Add Pull to Refresh to a React Native List from a Linear Issue](https://getrush.ai/run/add-pull-to-refresh/react-native/)

## The same job on other stacks

- [Add Deep Link Handling to a Tauri App](https://getrush.ai/run/add-deep-links/tauri/)
- [Add Deep Link Handling to an Electron App from a Linear Issue](https://getrush.ai/run/add-deep-links/electron/)
- [Add Deep Links to an Expo App](https://getrush.ai/run/add-deep-links/expo/)

## 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/)
