Gemini CLI and Next.js: A Practical Workflow Guide

Gemini CLI works well on Next.js projects when you run gemini in the project root and give it clear, file-level prompts. With a focused GEMINI.md, it can add route segments, convert components across the server-client boundary, write route handlers, and run your lint, typecheck, and test commands. Treat it as a junior Next.js engineer that edits code and verifies changes, not as a one-shot code generator. Gemini CLI

A practical fit for Next.js conventions and boundaries

Next.js projects are full of file conventions and hard boundaries that reward careful, verifiable changes. Gemini CLI can inspect the existing app/ or pages/ tree, read your current components, and produce diffs that respect those conventions when the instructions are clear. Because it runs in the terminal and can invoke package manager scripts, the natural loop of edit, lint, typecheck, test fits how Next.js developers already work. It is strongest on small, local tasks: adding loading.tsx or error.tsx, converting a form to a client component, creating a typed route handler, or moving a data fetch into a server component. For broader guidance on the agent itself, see How to use Gemini CLI: a step-by-step guide.

Give the agent your Next.js playbook with GEMINI.md

Before prompting, create a GEMINI.md at the project root. Keep it short, concrete, and Next.js-specific. The file should state commands, folder conventions, and rules that the agent must not break. A realistic starting point:

# GEMINI.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
- E2E: `pnpm e2e`

## Conventions
- App Router lives in `app/`; Pages Router lives in `pages/` only when the route cannot be migrated.
- Keep server components as the default; add `'use client'` only for state, effects, browser APIs, or event handlers.
- Put route handlers in `app/api/` and return `NextResponse.json()`.
- Colocate feature components in `features/<feature>/components/` and shared UI in `components/ui/`.
- Name tests `*.test.tsx` or `*.test.ts`.

## Rules
- After every change, run `pnpm lint` and `pnpm typecheck`; run `pnpm test` when touching logic.
- Do not edit `next.config.*`, `tsconfig.json`, or `middleware.ts` unless asked.
- Preserve React Server Component boundaries; do not pass functions or class instances from server to client components.
- Use `revalidatePath` or `revalidateTag` after mutations instead of setting `cache: 'no-store'` globally.
- Keep route handlers small and validate input with Zod.

This gives the agent the exact commands to verify work and the non-negotiables for server/client code. Update the commands if you use npm, Yarn, or Bun, and list only the test runner you actually have installed.

A small-step, verify-first workflow

Use a plan, small steps, run tests, review diff loop. Ask the agent to inspect relevant files before editing, limit each turn to one route segment, component boundary, or API route, and always run verification commands before showing the diff. Review git diff yourself or ask the agent to summarize it against your GEMINI.md rules.

Typical prompts that fit this loop:

• Inspect app/products/page.tsx and the existing data-fetching helpers, then add loading.tsx for the product route without changing the page component.
• Create a PATCH /api/orders/[id] route handler that validates the request body, calls the existing updateOrder service, and returns the updated order or a typed error.
• Extract the client search input from app/search/page.tsx into a separate SearchInput client component and keep the parent as a server component that reads searchParams.
• Add a Playwright test for the public blog index that checks the first three post cards render and the read more link points to the correct blog post.
• Refactor the contact form to use a server action in app/actions/contact.ts and keep the form component in a client component with useActionState.

After each prompt, ask the agent to run pnpm lint, pnpm typecheck, and the relevant subset of pnpm test. Only then move to the next step.

Where the agent helps and where it missteps in Next.js

The agent handles several tasks well when the prompt names the exact file and expected behavior: adding loading.tsx, error.tsx, and not-found.tsx; writing route handlers with typed responses; reading searchParams or params in page components; splitting a server component into a server parent and a client island; and generating Playwright tests from an existing route.

Watch it closely around the Next.js-specific pitfalls below. It may add 'use client' to a layout or page to pass data from a server component to a child, which defeats the server rendering benefits. It may edit next.config.ts or middleware.ts to solve a caching or auth issue instead of using revalidatePath or route-level logic. It may import a server-only module into a client component when moving code quickly. It may set revalidate = 0 or cache: 'no-store' globally instead of invalidating after mutations. And it may create a route handler for something that should be a server action, or vice versa.

If a diff touches next.config.*, middleware.ts, or adds 'use client' to a page, stop and ask the agent to explain why. Keep the explanation tied to the code, not to generic best practices.

Make the agent prove changes with lint, typecheck, and tests

Verification is where the agent earns its keep. Instruct it to run the checks below after every code change and to include the command output in the final summary. The exact commands come from your GEMINI.md.

Have the agent run pnpm lint and pnpm typecheck after every edit, and run pnpm build before considering a feature done. For changes to data fetching or forms, run the relevant Vitest or Jest tests; for navigation or user flows, run the Playwright test file. Always review the diff for server/client boundary changes before accepting, even if all checks pass. When something fails, a focused prompt such as Debug the failing typecheck in app/dashboard/page.tsx and preserve the server component works better than asking for a broad rewrite. For a deeper workflow, see How to debug code with AI: a practical workflow.

Parallel agents on one Next.js codebase with AgentVera

AgentVera is useful for larger Next.js work where you need several Gemini CLI agents running in parallel. Each agent can work in its own git worktree, so one can refactor the app/ directory while another adds Playwright tests without overwriting files. Automatic code review at the end of a turn catches Next.js-specific mistakes such as an accidental 'use client' on a server layout or a route handler that returns the wrong shape. Checkpoints let you roll back a turn if an agent changes server/client boundaries in the wrong direction. This setup fits tasks that touch many routes or require independent verification.

Keep the loop tight and the changes small

Gemini CLI can be a reliable Next.js pairing tool when you invest a little in project instructions and a tight verification loop. Keep changes small, make the agent run lint and typecheck, and review the diff before moving on. That discipline turns a terminal agent into a useful part of your Next.js workflow.