Cursor Agent is a terminal-first coding agent that reads a React Native repo, edits files, and runs project commands without leaving the CLI. Start it with cursor-agent in the project folder (see Cursor Agent for the core command overview) and it treats the repository as its working context. This guide covers the setup, prompts, and verification steps that keep a React Native codebase safe while the agent works.
Why Cursor Agent fits React Native
React Native development is a mix of JavaScript, TypeScript, native iOS and Android folders, Metro, and platform-specific quirks. Cursor Agent fits because it operates on the full repository: it can follow imports across JS and native boundaries, read Podfile and build.gradle changes, and run the exact commands a developer runs, such as npm test or npx tsc --noEmit. Unlike a chat-only assistant, it can modify multiple files and then run the verification loop, which matters when a navigation change touches a screen, a navigator, and a test. It also respects project instructions from AGENTS.md or .cursor/rules, so you can encode React Native conventions once and have every prompt obey them.
Project instructions that matter
Cursor Agent reads project instructions from AGENTS.md or .cursor/rules. For a React Native repo, keep the file short and specific: commands for install, start, test, lint, typecheck; folder conventions; and rules that prevent common mistakes. An example for an Expo + bare-compatible project:
# AGENTS.md for React Native
## Commands
- Install: `npm install`
- Start Metro: `npm start` (or `npx expo start` in Expo)
- iOS: `npm run ios` / `npx expo run:ios`
- Android: `npm run android` / `npx expo run:android`
- Test: `npm test -- --watchAll=false`
- Lint: `npm run lint`
- Typecheck: `npx tsc --noEmit`
## Folder conventions
- `src/` contains app code: `src/screens/`, `src/components/`, `src/navigation/`
- `src/theme/` for colors, spacing, typography
- `src/api/` for data fetching
- Native modules live in `ios/` and `android/`; do not edit generated files in `node_modules` or `.expo`
## React Native rules
- Do not change `ios/` or `android/` unless the task requires a native module or permission.
- Keep UI components platform-agnostic; use `Platform.OS` only when necessary.
- React Navigation patterns: use `createNativeStackNavigator` from `@react-navigation/native-stack`.
- Do not import from `react-native` types incorrectly; use named imports.
- Add new screens to `src/navigation/RootNavigator.tsx`.
- Never modify lockfiles manually; run `npm install` after dependency changes.
- If adding a dependency, update `package.json`, run `npm install`, then run tests and typecheck.Keep the file under 50 lines; the agent uses it as a constraint set, not a tutorial. Update it when you change the test runner, navigation pattern, or native module setup.
A plan-first working loop
Use a plan-first loop with Cursor Agent. Ask for a plan before edits, review the proposed diff, let it make small changes, then run the verification commands after each change. Do not ask for “fix everything” across native and JS in one turn. Example prompts:
- “Run the existing test suite and tell me which tests fail after my recent navigation change.”
- “Add a login screen using React Navigation and wire it to the existing auth context. Do not change native folders.”
- “Refactor the FlatList in HomeScreen to use FlashList with a fallback, then run the TypeScript check and relevant tests.”
- “Investigate why Metro shows ‘Unable to resolve module ./src/theme/colors’ and propose a minimal fix.”
- “Update the API client to handle 401 responses by clearing the token and navigating to SignIn, then add a Jest test.”
After each prompt, review the diff with git diff, discuss the verification output, and only then continue to the next small step. This loop follows the same discipline described in How to use Cursor CLI: a step-by-step guide.
Solid tasks and sharp edges in React Native
Cursor Agent is strong at routine React Native work: adding screens, wiring navigation, refactoring components, writing Jest tests, and fixing TypeScript errors. It is less reliable around native build configuration, platform permissions, and Metro cache issues. The table below matches typical tasks to good prompts and the specific areas to inspect.
| Task | Good prompt | Watch closely |
|---|---|---|
| Add a screen with React Navigation | “Add a profile screen and register it in the root navigator. Do not touch native folders.” | Navigation types, missing route props, stale navigation state |
| Add a native module | “Create a simple biometric auth module for iOS and Android, then add a JS wrapper.” | Podfile changes, autolinking, AndroidManifest permissions, incorrect Swift/Kotlin edits |
| Fix a Metro resolution error | “Metro says unable to resolve ’./src/theme/colors’. Investigate and propose a minimal fix.” | Caching issues, babel.config.js changes, premature cache clearing |
| Write tests for a hook | “Add Jest tests for useAuth with a mocked API client.” | Overmocking React Native modules, timer mocks, act warnings |
Beyond the table, watch these React Native pitfalls in diffs: the agent may add an npm package but forget to run pod install for a library with native code; it may edit index.js or App.tsx without understanding the existing entry point; it may add a platform-specific import without a Platform.OS guard; and it may suggest deleting Metro cache instead of fixing the resolution path. Never accept a native folder diff without a corresponding iOS and Android build check.
Verifying React Native changes
After the agent finishes a change, do not trust the summary alone. Either run the verification commands yourself or ask the agent to run them and paste the output. For a React Native repo, the minimum verification is:
npm test -- --watchAll=false— runs Jest once and catches regressions in utils, hooks, and components.npm run lint— ESLint with the project’s React Native config; catches unused imports and accessibility issues.npx tsc --noEmit— TypeScript check; essential for navigation param lists and component props.- If the diff touches
ios/orandroid/, runcd ios && pod install(bare workflow) ornpx expo run:ios/npx expo run:android(Expo) to verify the native build still resolves. - For Metro or import errors, ask the agent to run
npm start -- --reset-cacheornpx expo start --clear, then reproduce the error.
Treat the unit tests as the first gate, typecheck as the second, and a platform build as the final gate only when native files changed.
Parallel agents with AgentVera
AgentVera is a desktop app that runs several coding agents, including Cursor Agent, side by side in real terminal panels. For React Native work, the most useful features are parallel agents in separate git worktrees, automatic code review after each turn, checkpoints that undo a bad change with one click, and token budgets that stop an agent before it burns hours on a stuck native build. Separate worktrees prevent two agents from overwriting the same iOS or Android files, while review catches platform-specific breakage before it reaches the main branch.
Wrap-up
Cursor Agent becomes a reliable pair programmer for React Native when you give it a tight AGENTS.md, a plan-first loop, and verification commands after every change. Keep native changes small, run the platform builds for anything touching ios or android, and use parallel agents only with worktrees and review. For the broader Expo-to-stores path outside the agent loop, How to build a mobile app with AI: from Expo to the stores covers the full build and release flow.