# Cursor Agent for React Native: Practical Setup and Workflow

URL: https://agentvera.dev/en/blog/cursor-agent-for-react-native/ · Published: 2026-11-01

A practical guide to using Cursor Agent on React Native projects: setup with AGENTS.md, a plan-first workflow, safe prompts, and verification for Expo and bare apps.

**In short:**

- Cursor Agent works inside a React Native repo and follows AGENTS.md rules to edit JS, native, and navigation code safely.
- A plan-first loop with small prompts and verification after each change prevents native and Metro regressions.
- Parallel agents in separate worktrees with review and checkpoints make multi-agent React Native work safer.

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](/en/agents/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:

```markdown
# 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](/en/blog/how-to-use-cursor-cli/).

## 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/` or `android/`, run `cd ios && pod install` (bare workflow) or `npx 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-cache` or `npx 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](/en/blog/build-mobile-app-with-ai/) covers the full build and release flow.

## Frequently asked questions

**How do I start Cursor Agent on a React Native project?** Open a terminal in the project root and run cursor-agent. The agent reads the repository as context and follows instructions from AGENTS.md or .cursor/rules. For React Native, add commands and native folder rules to that file before the first prompt.

**Can Cursor Agent edit native iOS and Android code in a React Native app?** Yes, it can edit files in the ios and android folders, but you should restrict it with AGENTS.md rules and review native diffs carefully. Always run pod install and a platform build after any native change.

**What should I put in AGENTS.md for a React Native project?** Include install, test, lint, typecheck, and Metro commands; folder conventions for src, screens, and navigation; and rules like not editing native folders unless necessary. A short example file is shown in the guide.

**How do I verify Cursor Agent changes in React Native without breaking the app?** Run jest, eslint, and TypeScript checks after each change, then start Metro and test on a simulator. For native diffs, run pod install and a full iOS or Android build.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/