Run opencode in the root of a React Native project and it reads your project instructions from AGENTS.md, then edits TypeScript, JSX, and native files while running the same commands you would. This guide covers a practical workflow for using opencode on Expo and bare React Native apps, including setup, prompts, testing, and where to keep human oversight.
What opencode can do in a React Native codebase
React Native development has a wide error surface: TypeScript errors in component props, Jest mocks that drift from native modules, Metro cache issues that hide real changes, and native build failures from Podfile or Gradle changes. opencode can handle these because it works as a coding agent that runs shell commands and reads output, not as a chat-only model. In a React Native project, that means it can run npx tsc —noEmit after editing a screen, run a single Jest test with —watchAll=false, and inspect ESLint output for hooks rules. It understands platform-specific files like Home.ios.tsx and Home.android.tsx, and it can add or update React Navigation types without losing the existing route structure.
The practical value is in the loop: opencode edits code, starts a verification command, reads the failure, and applies a targeted fix. This reduces the number of times you have to copy a Metro or Jest error into a separate chat. The agent still needs clear boundaries, especially around native code and build artifacts, but the default behavior maps well to a TypeScript-first React Native codebase.
AGENTS.md setup for a React Native project
Create or update AGENTS.md in the project root. opencode reads this file automatically, so it should be short, concrete, and specific to the exact package manager, navigation library, and native workflow in use. Include the commands that are safe to run, the folder conventions, and rules that prevent expensive mistakes such as editing native projects or switching navigation libraries.
A useful AGENTS.md for a React Native project looks like this:
# AGENTS.md
## Commands
- Install dependencies: npm install
- Start Metro: npm start
- Run iOS: npm run ios
- Run Android: npm run android
- Typecheck: npx tsc --noEmit
- Lint: npm run lint
- Test one file: npm test -- --watchAll=false path/to/file.test.tsx
- Test all: npm test -- --watchAll=false
## Structure
- src/ for app code
- src/screens/ for React Navigation screens
- src/components/ for reusable UI
- src/navigation/ for navigators and route types
- src/api/ for data access and client code
- __tests__/ next to the source file, not in a top-level folder
## Rules
- Keep React Navigation as configured; do not change the navigation library.
- Do not edit ios/ or android/ unless the task explicitly asks for a native module or build change.
- Do not run pod install or Gradle commands without first explaining what will change.
- Prefer StyleSheet.create over inline style objects.
- Keep Metro-only imports out of shared business logic.
- Preserve existing Jest mock patterns; do not replace native module mocks with brittle inline calls.Keep the file short enough that the agent actually follows it. If the project uses Expo, replace the native commands with npx expo start, npx expo run:ios, and npx expo run:android, and add a rule that app.json changes must be explicitly requested. For a general opencode setup beyond React Native, see How to use opencode: a step-by-step guide.
Working loop for typical React Native tasks
Use a plan-first loop. Ask opencode to state which files it will touch and how it will verify before it edits. Then let it make one small change at a time, run the relevant checks, and show you the diff. For a React Native app, the smallest safe unit is often one component or one navigation change. If the agent starts editing native files or lockfiles without being asked, stop and review.
Example prompts:
- Add pull-to-refresh to the FlatList in src/screens/Home.tsx. Keep the current loading state, add an onRefresh prop, and update the test in tests/Home.test.tsx.
- Set up a new stack navigator under src/navigation/ for an onboarding flow. Add typed route params and a basic render test using the existing test setup.
- Fix the failing test in tests/Profile.test.tsx. Run only that file first, explain the mock mismatch, then change the smallest amount of code and re-run the test.
- Add a typed API client in src/api/ for the current backend. Use the existing request wrapper, add error types, and write one test for parsing a successful response.
After each change, review git diff before moving on. If the diff touches more than the agreed files, ask opencode to explain. The agent should run npx tsc —noEmit after TypeScript changes and the targeted Jest command after component changes. Do not accept “should work” as the final state.
Typical React Native tasks and pitfalls to watch
opencode is reliable for most React Native UI and test tasks when the project has clear conventions. It handles refactoring components, moving styles to StyleSheet.create, adding typed route params, updating Jest mocks for react-native modules, and fixing TypeScript errors across platform-specific files. It also works well for navigation changes because React Navigation types give it enough context.
Watch it closely in a few areas that are specific to React Native:
| Area | opencode tends to do well | Verify manually |
|---|---|---|
| Components and screens | Extracting reusable components, adding props, updating styles | Fast Refresh state, gesture handling, visual layout on device |
| Jest tests | Fixing mock mismatches for react-native and @react-native modules | Snapshots from native components, async timers, act warnings |
| Navigation | Adding typed routes and stack screens | Deep linking behavior, back button behavior, safe area insets |
| Native modules | Creating wrapper files and JS APIs | Podfile, Gradle, linking, permission strings in Info.plist and AndroidManifest.xml |
The biggest pitfalls are native project edits, package manager lockfile conflicts, and stale Metro state. If the agent edits ios/Podfile.lock or android/build.gradle, run the native build on a real simulator or device. If it changes a Babel plugin or metro.config.js, clear Metro cache or restart with npx react-native start —reset-cache for bare workflows, or npx expo start —clear for Expo. Also watch for changes to app.json in Expo: schema properties, plugins, and permission strings often need a rebuild, not just a Metro refresh.
Testing and verifying React Native changes
Make verification a hard requirement. For every change, ask opencode to run npx tsc —noEmit, the targeted Jest test, and the linter if it touched component code. Use the exact commands from AGENTS.md. In a React Native project, type checking alone is not enough because Metro can resolve imports that TypeScript accepts but the bundler fails on, and native modules can compile only in a full build.
For test files, prefer React Native Testing Library and the existing mock setup. opencode should preserve the project’s jest.setup.js or jest.setup.ts pattern and reuse mocks for react-native and third-party native modules. If a test fails on a native module, ask opencode to update the mock, not to skip the test or use jest.mock inline unless that is already the convention.
For native changes, do not rely on the agent’s judgment. After opencode edits ios/ or android/, run the app on one supported platform. In a bare project, execute pod install in ios/ if the Podfile changed, then npm run ios; in Expo, use npx expo run:ios or npx expo run:android to regenerate native projects. If the change only touches JavaScript, a Metro reload may be enough, but a clean test run still catches most regressions.
Parallel agents on one React Native project with AgentVera
When you run several agents on one React Native codebase, AgentVera gives each agent its own real terminal and, when needed, its own git worktree, so changes to ios/, android/, and shared TypeScript files do not overwrite each other. Automatic code review after each turn links findings to file:line, which matters when native module wrappers or Metro configs are touched. Checkpoints let you undo a single turn if a bad edit breaks the build, instead of re-cloning the repo. This setup reduces the main risk of parallel React Native work: two agents changing the same native folder or lockfile at once. Best tools to run AI coding agents in parallel (2026).
Wrapping up opencode for React Native
opencode fits React Native projects when you treat it as a tool that edits, runs checks, and explains failures under your supervision. Put the build, test, and lint commands in AGENTS.md, keep tasks small, review diffs before native changes, and verify on a device or simulator before merging. That loop gives the agent enough context to move quickly without letting it make native changes you will only discover in CI.