opencode and React: a practical guide for coding agents

opencode is a terminal coding agent you run from your React project root. It reads project instructions from AGENTS.md, so you can make it follow your Vite, Vitest, and component conventions. This guide covers a practical setup, a repeatable working loop, common React tasks and pitfalls, testing, and how to run several agents safely.

Why opencode suits React work

React changes often span several files: a component, its hook, test, and Storybook story. opencode can update them in one pass when AGENTS.md tells it where things live. It understands JSX, props, hooks, and common patterns like lifting state up, memoization, and context providers. That makes it good for mechanical refactors such as extracting a custom hook, converting class components to functions, or migrating state from useState to useReducer. It is not a replacement for a senior React review; it will guess conventions unless you write them down. Concrete win: give it a failing test and ask it to make it pass, then inspect the diff.

Setting up the React project for the agent

Before running opencode, create AGENTS.md at the repo root. Keep it factual: commands, folder layout, and React-specific rules. opencode reads this on each session, so it will not repeatedly ask how to run tests or where components go. A realistic file for a Vite + TypeScript + Vitest + Storybook project looks like this:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev` (Vite)
- Build: `pnpm build` (tsc -b && vite build)
- Lint: `pnpm lint` (eslint .)
- Test: `pnpm test` (vitest run)
- Test watch: `pnpm test:watch`

## React conventions
- Function components only; no default exports for components.
- Put reusable UI components in `src/components/ui/`, feature components in `src/features/<name>/`.
- Use named exports; co-locate tests as `*.test.tsx`.
- Custom hooks go in `src/hooks/` and must start with `use`.
- Use TypeScript strict mode; avoid `any`.
- State: use React Query for server state and Zustand for client state; do not put server data in Redux.
- Styling: CSS modules in the same folder.
- Storybook stories live in `src/components/ui/__stories__/`.
- Never change `vite.config.ts`, `tsconfig.json`, or `eslint.config.js` without being asked.
- After every change, run `pnpm lint` and `pnpm test`.

The commands block tells opencode which package manager and scripts to use, so it can run lint and tests instead of guessing. The React conventions block prevents common issues such as adding a default export, putting server state in the wrong store, or editing Vite config without permission. If the agent suggests a change outside these rules, ask it to explain before proceeding. For a broader setup walkthrough, see How to use opencode: a step-by-step guide.

A working loop for React changes

Use a tight loop: plan, small steps, run the tests, review the diff.

1. Write a focused prompt describing the exact React change and the files it may touch.
2. Let opencode propose a diff; ask it to include tests or Storybook stories if that is your convention.
3. Run pnpm lint and pnpm test; if something fails, paste the error back.
4. Review git diff for accidental changes to Vite config, package scripts, or unrelated components.
5. Commit only when the test suite is green.

Example prompts for common React work:

• Create a useDebouncedValue hook in src/hooks/useDebouncedValue.ts with unit tests and update SearchInput to use it.
• Refactor UserList to use React Query instead of a local useEffect fetch; keep the loading, error, and empty states.
• Add a Storybook story for PrimaryButton covering default, disabled, and loading variants; run existing tests afterward.
• Fix the failing ShoppingCart test by making the update function use the previous state instead of the closed-over value.
• Upgrade the routing in src/features/account from the old React Router patterns to the current data router style without changing component behavior.

Typical React tasks and where to watch closely

opencode handles many React tasks well, especially when you give it a small scope and an existing test to anchor behavior.

Watch generated React code closely for specific issues: stale closures in useEffect or event handlers, missing dependency arrays, mutating state directly, and unstable object or function props passed to memoized children. Be skeptical when the agent adds useMemo or useCallback without a measured problem; premature memoization makes code harder to read. Check list keys: generated lists may use the array index, which breaks state when items reorder. When opencode touches context providers, portals, or forms, run the full test suite because failures can appear in unrelated components. Prefer test queries based on roles and accessible names; only accept test IDs when no semantic query works.

Testing and verification with opencode

Ask opencode to write tests alongside the implementation, not as an afterthought. Use Vitest and React Testing Library with userEvent rather than fireEvent for realistic interactions. Tests should assert on visible behavior and accessibility roles, not on internal state or component names. Avoid brittle snapshot tests; if you must snapshot, keep the scope to tiny presentational components.

After each agent turn, run pnpm test and pnpm lint. If a test fails, include the assertion error and the component code in the next prompt; opencode can often fix it in one iteration. For Storybook projects, ask for stories covering loading, error, empty, and interactive states, then verify them manually in Storybook. A strong agent output is a component change plus a test that would fail before the change; ask for that when possible. For a comparison with other CLI agents, see opencode vs Claude Code: an honest comparison.

Running several agents with AgentVera

AgentVera runs opencode and other real CLI agents side by side, each in its own terminal panel. For React work, the most useful features are parallel worktrees, automatic code review, checkpoints, and token budgets. Worktrees let one agent refactor hooks while another builds component tests without overwriting files. Automatic code review catches React-specific issues like stale closures or broken dependency arrays when a turn ends. Checkpoints allow you to undo a bad refactor and replay the session step by step. Token budgets stop a long migration from consuming your whole daily allocation while preserving the conversation.

Wrapping up

Use opencode like a fast junior pair programmer: put your React conventions in AGENTS.md, ask for small diffs with tests, and verify every change with the test runner. When a task grows too large, split it into hooks, components, and tests; when you need parallel work, use worktrees. Keep your prompts specific, and always review the diff before committing.