# Gemini CLI for React: Practical Workflow Guide

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

Learn how to use Google’s Gemini CLI on React projects: set up GEMINI.md, prompt for components and hooks, run Vitest and Storybook checks, and avoid state pitfalls.

**In short:**

- Gemini CLI works best on React when you define build, test, lint, and component conventions in GEMINI.md.
- Ask for small, test-verified changes and always review diffs around hooks, effects, and state updates.
- For parallel React work, run agents in separate git worktrees and cap token usage to avoid conflicting edits.

Gemini CLI is a terminal coding agent from Google that you start with `gemini` inside your React project. It reads GEMINI.md for project rules and can edit components, hooks, tests, and stories. With a strict verification loop around Vitest, React Testing Library, and TypeScript, it becomes a practical pair programmer for React work.

## Why Gemini CLI fits React development

React work is usually a tree of small, composed units: components, hooks, contexts, and tests. Gemini CLI operates on the file system and terminal, so it can find the component that renders a piece of UI, read its props and state, and make a change across the component, its test, and its Storybook story in one pass. Because it can run `npm run build`, `npm run lint`, and `npm run test -- --run`, it catches JSX errors, missing keys, unused imports, and TypeScript mismatches before you do. It handles common React patterns such as lifting state, converting useState to useReducer, adding error boundaries, and writing testing-library queries. For codebases that use Vite, Vitest, and Storybook, the agent can work with the exact commands already in package.json, so it does not need a special setup beyond GEMINI.md.

## Setting up GEMINI.md for a React project

GEMINI.md is the project-level instruction file that Gemini CLI reads on startup. For a React repo, keep it short but specific: declare the package manager, the commands for dev, build, test, lint, and typecheck, the folder layout, and the rules that matter for your team. If you use a state library or CSS approach, say so; otherwise the agent may invent conventions. A realistic GEMINI.md for a Vite + TypeScript + Vitest + React Testing Library project looks like this:

```markdown
# Commands
- Install: npm install
- Dev server: npm run dev
- Build: npm run build
- Test once: npm run test -- --run
- Test watch: npm run test
- Lint: npm run lint
- Typecheck: npx tsc --noEmit

# React conventions
- Use function components and hooks only. No class components.
- Components live in src/components/<Name>/<Name>.tsx with a co-located test and story.
- Hooks live in src/hooks/use<Name>.ts with a test.
- Server state uses React Query; local UI state uses Zustand.
- Styling uses CSS Modules, one file per component.
- Effects must have a clear dependency array; do not disable eslint rules without a comment.
- Tests use React Testing Library and user-event. Prefer accessible queries.
- Before editing a component, read its test and story. After editing, run the related test file and npm run lint.
```

Keep this file under version control and update it when you change lint rules, folder structure, or state-management choices. The agent will treat these as hard constraints, so do not add vague guidance such as 'write clean code'; give React-specific rules like 'do not introduce memoization without a failing performance test.' For a step-by-step overview of the tool itself, see [How to use Gemini CLI: a step-by-step guide](/en/blog/how-to-use-gemini-cli/).

## A working loop for React tasks

The most reliable loop is plan, implement small, verify, review. Start by telling the agent the user-visible behavior you want, not the internal solution. Ask it to propose a plan before editing files. Then have it make one focused change, run the relevant test file or the full suite, and show a diff. Review the diff in a git client or with `git diff` before committing.

Example prompts for typical React tasks:

- Add a loading state to the UserList component. Show a skeleton row while useUsers is fetching, and keep the existing error state. Update UserList.test.tsx to cover loading, success, and error.
- Refactor the counter logic in Dashboard to use useReducer. Keep the exact current behavior and update its test and story.
- Write a Storybook story for the Button component covering primary, secondary, disabled, and loading variants.
- Fix the failing test in src/components/ProductCard/ProductCard.test.tsx. Do not change the component API.
- Run the test suite, then fix any regressions you introduced in the last change. Show me the diff after.

Each prompt asks for a small, verifiable outcome. If the agent suggests a larger refactor, ask it to split it into steps or create a git worktree.

## What Gemini CLI handles well and where to watch closely

Gemini CLI is strong at mechanical React changes: adding props, converting class components to functions, writing tests from existing behavior, generating stories, and fixing type errors. It is less trustworthy when it decides to refactor state management, introduce effects, or add memoization. The table below maps common tasks to useful prompts and the exact things to review.

| Task | Good prompt | Watch closely |
|------|-------------|---------------|
| Add a prop to a component | Add an optional `size` prop to Button with values 'sm', 'md', 'lg'. Update types, default props, and the story. | Prop drilling, unused props, test updates |
| Convert useState to useReducer | Refactor the form state in SignupForm to useReducer without changing behavior. Update tests. | Action types, initial state, stale action payloads |
| Fix a hook dependency bug | The effect in useDebouncedValue triggers too often. Find the missing dependency and fix it without causing an infinite loop. | Dependency arrays, cleanup, object or function identity |
| Write a test from a component | Write a React Testing Library test for Accordion. Cover open, close, and keyboard toggling. | Accessible queries, event simulation, async state |
| Add a Storybook story | Add a story for Modal covering open, closed, and nested focus trap. | Args, decorators, accessibility addon |

Specific React pitfalls to review in every diff:

- Effects and dependencies: The agent may add an effect that runs on every render or omits a dependency to silence lint. Reject any change that disables exhaustive-deps without a clear reason.
- State updates: React state updates are async. Check that the agent does not read a state variable immediately after setting it and expect the new value.
- Stale closures: In callbacks passed to `useEffect`, `useCallback`, or event handlers, the agent can capture an old value. Verify that refs or dependency arrays are correct.
- Keys and reconciliation: When the agent renders lists, ensure the `key` is stable and unique, not an index on a reorderable list.
- Memoization: It may wrap every component in `React.memo` or every callback in `useCallback`. Reject optimization without a benchmark or a failing render test.
- Test overfitting: The agent may write tests that assert implementation details or snapshots that break on any benign change. Prefer tests that assert user-visible behavior via roles and text.

## Testing and verification with Gemini CLI

Do not accept a change that only compiles. Ask the agent to run `npm run test -- --run`, `npm run lint`, and `npx tsc --noEmit` after every non-trivial edit. For React, Vitest with React Testing Library is the primary safety net. The agent can run a single file with `npx vitest run src/components/UserList/UserList.test.tsx` when you want fast feedback, and the full suite before a commit. If a test fails, tell the agent to fix the regression, not to remove or skip the test unless you explicitly ask.

Storybook is useful for visual and interaction checks. Ask the agent to update the relevant story when it changes a component API or adds a new variant. You can then run `npm run storybook` locally and click through the story. The agent cannot see the rendered UI except through test output and build errors, so pair its edits with your own visual review for layout, focus states, and animation.

## Running several agents on one React project with AgentVera

When you split a React codebase into parallel tracks such as one agent adding a feature, another fixing a flaky test, and another updating Storybook, AgentVera lets you run Gemini CLI alongside other coding agents in real terminal panels. Each agent can work in its own git worktree, so changes to components, hooks, and tests do not overwrite each other. Automatic code review sends an agent’s diff to a second model, which catches React-specific problems like stale closures or missing effect dependencies with file:line links. Checkpoints let you undo any risky refactor in one click, and token budgets keep a long test-fix loop from exhausting your quota while preserving the conversation.

## Wrap-up

Gemini CLI is most useful on React projects when you treat it as a junior engineer with great tooling: give it a precise GEMINI.md, small tasks, and a strict verify loop. Run the tests, review the diff for React-specific pitfalls, and use git worktrees or an orchestration tool when you need parallel work. For more on the day-to-day workflow, see [AI pair programming: how to work with a coding agent](/en/blog/ai-pair-programming/) and the [Gemini CLI](/en/agents/gemini-cli/) reference.

## Frequently asked questions

**How do I set up Gemini CLI for a React project?** Install Gemini CLI, open your React project folder, and run gemini. Create a GEMINI.md file with your build, test, lint, and typecheck commands plus React-specific component and hook conventions.

**What should I put in GEMINI.md for a React project?** Include npm or pnpm commands, folder structure for components and hooks, state management choices, styling approach, and rules for effects, tests, and TypeScript. Keep it concrete and update it when conventions change.

**Can Gemini CLI run React tests and Storybook?** Yes. Ask it to run npm run test -- --run, npx tsc --noEmit, and npm run lint after changes. It can also update Storybook stories, but you should still visually inspect the rendered components locally.

**How do I avoid Gemini CLI breaking React hooks or state?** Review every diff for effect dependencies, stale closures, and async state updates. Ask for small, test-verified changes and reject any change that disables lint rules or adds memoization without a clear reason.

---

**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/