All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

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

Keep reading