# Add Biometric Login to a React Native App

Yes. An agent adds a Face ID and fingerprint lock to your Expo React Native app, with a settings toggle, an unlock screen, tests and a config plugin, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-biometric-auth/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 how sign-in works before it adds a lock in front of it. In an Expo app like obytes/react-native-template-obytes, `package.json` pins `expo` `~54.0.32`, `expo-router` `~6.0.22` and `react-native` `0.81.5`, is installed with pnpm 10, and runs `check-all` as lint, type-check, translation lint and Jest together. Auth is a Zustand store in `src/features/auth/use-auth-store.tsx` with `signIn`, `signOut` and `hydrate`, and the token lives in MMKV through `src/lib/auth/utils.tsx` and `src/lib/storage.tsx`. `src/app/(app)/_layout.tsx` redirects to `/onboarding` on first launch and to `/login` when the status is `signOut`, and `src/app/_layout.tsx` calls `hydrateAuth()` before rendering. The settings screen in `src/features/settings/` is built from `settings-item.tsx` rows with strings from `src/translations/en.json` and `ar.json`, which the `lint:translations` script checks for matching keys.

The agent installs `expo-local-authentication` with `pnpm expo install` so the version matches the SDK, and adds its config plugin to the `plugins` array in `app.config.ts` with a `faceIDPermission` string, which writes `NSFaceIDUsageDescription` into the iOS Info.plist at prebuild and adds the biometric permission on Android. It writes `src/lib/auth/biometrics.ts` with three functions over the module: whether the device has hardware and an enrolled biometric, a prompt that calls `authenticateAsync` with a message and no device-passcode fallback, and a preference stored in MMKV under a `BIOMETRIC_LOCK` key with a `useMMKVBoolean` hook in the style of `use-is-first-time.tsx`.

The lock itself is a new auth status. `hydrate` in the store now checks the preference: a stored token with the lock on sets status `locked` instead of `signIn`, and a new `unlock` action moves it to `signIn` after a successful prompt. `src/app/(app)/_layout.tsx` gains a redirect to a new `src/app/unlock.tsx` screen when the status is `locked`; the screen prompts on mount, offers a retry button and a sign-out link using the existing `Button` from `src/components/ui`, and prompts again when the app returns to the foreground after being backgrounded, read from `AppState`. The settings screen gets a `biometric-item.tsx` row with a switch that is disabled, with an explanation, when the device has no enrolled biometric, and the new strings go into both `en.json` and `ar.json` so the translation lint stays green.

Tests follow the suite that exists. The agent adds a mock for `expo-local-authentication` to `jest-setup.ts` beside the MMKV and localization mocks, then writes tests for the store transitions, for the unlock screen using the `setup` helper from `src/lib/test-utils.tsx`, and for the settings row's disabled state. It runs `pnpm check-all`, which covers `eslint .`, `tsc --noemit`, the translation lint and Jest, and runs `npx expo-doctor` as the `expo-doctor.yml` workflow does. Biometric prompts need a device or simulator the sandbox does not have, so the Maestro flows under `.maestro/auth/` are left unchanged with the lock off by default, and the pull request says plainly that the prompt was not exercised on hardware.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add biometric login to this Expo React Native app. Read package.json, app.config.ts, src/app/_layout.tsx, src/app/(app)/_layout.tsx, src/features/auth/use-auth-store.tsx, src/lib/auth/utils.tsx, src/lib/storage.tsx, src/lib/hooks/use-is-first-time.tsx, the settings components, src/translations/en.json and ar.json, jest-setup.ts and the Maestro flows first. Install expo-local-authentication with pnpm expo install and add its config plugin to app.config.ts with a Face ID permission string. Add src/lib/auth/biometrics.ts with availability, prompt and a BIOMETRIC_LOCK preference stored in MMKV. Add a locked status to the auth store: hydrate sets it when a token exists and the lock is on, and an unlock action clears it after a successful prompt. Add src/app/unlock.tsx that prompts on mount and on return to the foreground, with retry and sign-out, and redirect to it from the (app) layout when locked. Add a settings row with a switch, disabled with an explanation when no biometric is enrolled, with strings in both translation files. Mock the module in jest-setup.ts and add tests for the store, the unlock screen and the settings row. Run pnpm check-all and npx expo-doctor, leave the Maestro flows unchanged with the lock off by default, and open a pull request that lists the files and states that the prompt was not run on a device.",
  "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 changing `package.json` and `pnpm-lock.yaml`, `app.config.ts`, `src/features/auth/use-auth-store.tsx`, `src/app/(app)/_layout.tsx`, the settings screen and both translation files, and adding `src/lib/auth/biometrics.ts`, `src/app/unlock.tsx`, a `biometric-item.tsx` settings row, the Jest mock in `jest-setup.ts` and the new test files. The login form, the onboarding flow and the Maestro flows are untouched, and the lock is off until a user turns it on in settings.

The description lists each file with one line on what it does, the permission string written to the Info.plist, and the `pnpm check-all` and `expo-doctor` output, and it says in its own paragraph that the biometric prompt was not exercised on a device. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps the install, lint, type-check and Jest runs, so a reviewer can see what passed rather than read that it did.

Before merging, a reviewer runs the app on a simulator or device with a biometric enrolled, turns the lock on, backgrounds and resumes the app, and checks that cancelling the prompt leaves the user on the unlock screen with sign-out available. A follow-up on the same session can add a Maestro flow for the settings switch, or make the lock the default for new installs.

## Run it on every Linear issue labelled auth

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `auth` label. When someone labels an issue such as "require Face ID when the app comes back from the background", the trigger places the issue after the prompt, the run reads what the issue asks for, and the pull request links back to it. Only label changes made by a person in your Rush org fire the trigger, and the automation starts at most `max_runs_per_hour` runs in an hour.

From a script, the same body goes to `POST /o/{org}/sessions` with the repository in `resources`, the issue URL as a second resource, and a `request_id` that is a UUID v5 of the issue id so a retry returns the run already started. Give the key a `webhook_url` and every run the key starts posts `run.completed` with `data.session_url`, from which a handler reads the pull request link.

## Why run it on Rush?

A biometric lock touches the places a mobile app is least forgiving about: the store that decides whether a user is signed in, the layout that redirects, the native config that needs a permission string, and two translation files that must agree. The agent reads each of those in its own sandbox before changing them and proves what can be proved there, the type check, the lint and the unit tests, while saying clearly what still needs a device.

The install, lint, type-check and Jest output stay in the run's transcript, so the review starts from evidence, and the laptop that filed the issue is free while pnpm and Jest run. Several apps built from the same template can get the feature at once, each in its own sandbox and its own pull request.

## Frequently asked questions

### Does it test the fingerprint or Face ID prompt itself?

No, and it says so. The sandbox has no device or simulator with an enrolled biometric, so the module is mocked in Jest and the store, screen and settings row are tested against the mock. The pull request asks the reviewer to run the prompt on hardware before merging.

### Is the lock on for everyone after the pull request merges?

No. The preference defaults to off, so existing users see no change until they turn the switch on in settings. Making it the default for new installs is a one-line change in `src/lib/auth/biometrics.ts` that the pull request leaves to you.

### Why does it need a change to app.config.ts?

Because iOS refuses Face ID without an `NSFaceIDUsageDescription`, and the `expo-local-authentication` config plugin writes it at prebuild from the `faceIDPermission` string in `app.config.ts`. The agent adds the plugin to the existing `plugins` array next to `expo-router` and `expo-localization`.

### Will the translation lint fail on the new strings?

Not if both files get the keys, which is why the agent adds the biometric strings to `en.json` and `ar.json` in the same commit and runs `pnpm lint:translations` as part of `check-all`. An Arabic reviewer may still want to improve the wording, and the pull request says the Arabic strings are a first pass.

## More React Native jobs

- [Add Crash Reporting to a React Native App](https://getrush.ai/run/add-crash-reporting/react-native/)
- [Add Deep Links to a React Native App](https://getrush.ai/run/add-deep-links/react-native/)
- [Set Up GitHub Actions CI for a React Native App](https://getrush.ai/run/add-github-actions-ci/react-native/)

## The same job on other stacks

- [Add Biometric Login to an Expo App from a Linear Issue](https://getrush.ai/run/add-biometric-auth/expo/)
- [Add Fingerprint and Face ID Login to a Flutter App](https://getrush.ai/run/add-biometric-auth/flutter/)

## More jobs like this: Turn a Linear label into a PR

- [Add a Blog Dashboard to a Filament Admin Panel from a Linear Issue](https://getrush.ai/run/add-blog-dashboard/filament/)

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