# Gemini CLI React Native: a practical developer guide

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

Use Gemini CLI in a React Native project: setup GEMINI.md, plan small edits, run Jest and Metro checks, and avoid common native pitfalls.

**In short:**

- Start Gemini CLI with gemini in the project root and give it a GEMINI.md that encodes your React Native build, test, and lint commands.
- Use a tight loop: plan, make one small change, run Jest and TypeScript checks, and review the diff before continuing.
- Watch closely around native modules, Metro config, and platform-specific files; do not let the agent guess native linking or versions.

Gemini CLI is a terminal coding agent that you start by running `gemini` in the root of a React Native project. It reads a GEMINI.md file for project-specific instructions and can plan changes, edit files, and run commands such as `npm test` or `npx tsc --noEmit`. For background on the agent itself, see [Gemini CLI](/en/agents/gemini-cli/). This guide focuses on making it productive in Expo or bare React Native work.

## Why Gemini CLI fits a React Native workflow

React Native development already lives in the terminal: Metro, Jest, TypeScript, npm, and platform build tools. Gemini CLI fits that workflow because it operates in the same project directory and can run the exact scripts you already use. It reads multiple files at once, so it can follow a component from a screen through navigation, props, and hooks to a test file. That makes it useful for repetitive refactors such as changing a prop across call sites, adding navigation routes, or keeping platform-specific `.ios.tsx` and `.android.tsx` files in sync. It also handles generated config files well when you give it rules, but it does not replace Xcode or Android Studio for visual layout or native debugging.

## Give the agent a project brain with GEMINI.md

The single highest-leverage step is a good GEMINI.md in the project root. Gemini CLI reads this file at startup, so it should contain the commands that make your project testable and the rules that prevent common React Native mistakes. If you are new to the agent workflow, [How to use Gemini CLI: a step-by-step guide](/en/blog/how-to-use-gemini-cli/) gives a step-by-step walkthrough for starting and steering the agent. A concise example for a React Native project looks like this:

```
# React Native project rules for Gemini CLI

## Commands
- install: npm install
- test: npm test -- --watchAll=false
- typecheck: npx tsc --noEmit
- lint: npm run lint
- start Metro: npx expo start --clear
- export Android: npx expo export --platform android
- run iOS: npx expo run:ios

## Folder conventions
- src/screens: screen components
- src/components: reusable UI
- src/navigation: React Navigation stacks/tabs
- src/api: API client and hooks
- src/__tests__: Jest tests next to source

## Rules
- Do not edit ios/ or android/ manually unless the task requires native module code.
- For native dependencies, prefer Expo config plugins or ask before changing Podfile or build.gradle.
- Keep platform-specific code in src/**/*.ios.tsx and *.android.tsx.
- Never change babel.config.js, metro.config.js, or tsconfig.json without an explicit user request.
- Always run typecheck and tests after changing a shared component or hook.
```

Keep the file short enough that the agent actually follows it; if you add twenty rules, it will ignore the important ones.

## The day-to-day loop: plan, small edits, verify

Treat Gemini CLI like a fast junior engineer who can type but should not own the final merge. Start from a clean `git status`, then ask for a plan before any file changes. Let the agent make one small logical change, run the project’s checks, and review the diff. If the change touches shared components or platform-specific files, run the checks yourself as well. This is the closed loop described in [AI pair programming: how to work with a coding agent](/en/blog/ai-pair-programming/); it works especially well for React Native because broken changes often only appear at bundle time or inside a native module.

Typical prompts:

- Map the current React Navigation structure and suggest the smallest change to add a Settings screen without altering the existing bottom tabs.
- Add a `useDebouncedValue` hook in `src/hooks/useDebouncedValue.ts`, export it from the hooks index, and add a Jest test for the 300 ms default delay.
- Refactor `ProductCard` to take a `variant` prop instead of `isFeatured`; update the two call sites in `HomeScreen` and `SearchScreen` and run typecheck.
- Run `npx tsc --noEmit` and fix the first five type errors one at a time, showing the diff after each file.
- Review the current `git diff` and point out any React Native-specific risks before I commit.

Each prompt keeps the change bounded and verification explicit.

## Where Gemini CLI is strong and where to watch closely

Gemini CLI handles text-heavy React Native tasks well: adding screens, refactoring components and hooks, updating API calls, writing tests, and fixing TypeScript errors. It is less reliable when a change requires native module knowledge, Metro resolution details, or platform build settings. In those areas, let the agent propose a change but verify it against the real toolchain before trusting it.

| Task type | What the agent does well | What to verify manually |
|---|---|---|
| Navigation | Adds stack or tab screens and updates route types. | Does the new screen stay within the existing navigator? Are initial params correct? |
| Component refactor | Renames props, extracts hooks, updates call sites. | Do all `.ios.tsx` and `.android.tsx` variants still match the same props? |
| Test creation | Writes Jest and React Native Testing Library tests. | Do tests mock native modules such as AsyncStorage or Reanimated correctly? |
| Metro config | Suggests alias or resolver changes. | Are babel.config.js, metro.config.js, and tsconfig paths all in sync? |

Watch closely around these React Native-specific areas:

- Native modules and linking: if the agent wants to edit `Podfile`, `build.gradle`, `AndroidManifest.xml`, or `AppDelegate`, require it to explain the exact native change and wait for approval.
- Metro and Babel: plugin order for `react-native-reanimated` or `react-native-gesture-handler` matters; an agent that reorders babel plugins can break the app at runtime.
- Expo config plugins: for Expo projects, prefer `app.json` plugin entries over manual native edits; otherwise `expo prebuild` will overwrite the change later.
- Platform-specific files: a change to `Component.tsx` without updating `Component.ios.tsx` and `Component.android.tsx` can cause silent drift.
- Package versions: the agent may add a package that requires a newer React Native or Expo SDK; check the peer dependencies before committing.

## Testing React Native changes with the agent

Make the agent run non-interactive versions of your checks. For Jest, use `npm test -- --watchAll=false` so the command exits. For types, use `npx tsc --noEmit`. For a bundle-level sanity check, `npx expo export --platform web` or `--platform android` will catch import or Metro resolution errors before you open a simulator. For bare React Native, `npx react-native bundle` is an equivalent check. After a native-related change, run `cd ios && pod install` yourself and inspect the generated diff; do not let the agent assume the pods are fine. Always review `git diff` after each step and ask the agent to summarize which files changed and why.

For component tests, ask the agent to add tests with `@testing-library/react-native`, but warn it to mock native modules that use `NativeModules` unless you have a mock preset.

## Parallel agents on one codebase with AgentVera

AgentVera runs Gemini CLI in a real terminal panel side by side with other coding agents. For React Native, the most valuable parts are parallel agents in separate git worktrees, so one can work on `src/` while another touches `ios/` without file collisions; an automatic second-model code review after each turn that links findings to `file:line`, which catches native module or Metro config mistakes early; checkpoints that let you undo a risky `pod install` or platform-specific edit in one click and replay the session; and token budgets that stop runaway processes but keep the conversation. For more on orchestrating multiple agents, see [AI agent orchestration for coding: 5 patterns and tools](/en/blog/ai-coding-agent-orchestration/).

## Wrap-up: keep the agent on a short leash

The best results come from tight constraints: a clear GEMINI.md, one small change at a time, non-interactive verification commands, and a human review of every diff that touches native or platform-specific code. With that loop, Gemini CLI can take over a large share of the repetitive screen, hook, and test work in a React Native project, leaving the native integration decisions to you.

## Frequently asked questions

**Can Gemini CLI run React Native commands like npm test and npx expo start?** Yes, Gemini CLI can execute shell commands in the project directory, including npm test, npx tsc --noEmit, and npx expo export. For long-running interactive commands like Metro, run them yourself; ask the agent to use non-interactive variants so it gets a clean exit code.

**What should I put in GEMINI.md for a React Native project?** Include the exact build, test, lint, and typecheck commands, folder conventions, and rules for platform-specific files and native modules. A short file is better than a long one; specify that ios/ and android/ should not be edited without explicit approval.

**Does Gemini CLI understand React Native-specific files like App.tsx, babel.config.js, and metro.config.js?** It reads and edits any text files in the project, so it can handle App.tsx, babel.config.js, metro.config.js, and platform-specific files. However, it may not know your exact Metro alias or Babel plugin order without hints in GEMINI.md.

**How do I prevent Gemini CLI from breaking native dependencies or running pod install incorrectly?** Add a rule in GEMINI.md that native changes and pod install require explicit user confirmation. Review the diff of any change to Podfile, build.gradle, or AndroidManifest.xml before running the native 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/