Gemini CLI is a terminal coding agent from Google that can read your Nuxt project, follow GEMINI.md, edit files, and run commands. Start it inside a Nuxt folder by running gemini and give it focused tasks. This guide covers setup, prompts, testing, and pitfalls for getting reliable Nuxt work from the agent.
Concrete reasons Gemini CLI fits Nuxt development
Nuxt’s file-based routing and auto-imports give Gemini CLI a small, predictable surface. Instead of explaining a custom router or prop drilling, you can say “create a page at pages/foo.vue and a server route in server/api/foo.get.ts.” The agent can edit a complete vertical slice: page, composable, server route, and Vitest test. It can run npm scripts and read the resulting errors, so it can iterate on type errors, lint failures, and failing tests without you manually pasting output. This works well when GEMINI.md encodes the Nuxt conventions the agent must not violate.
Prepare your Nuxt repo with GEMINI.md
The most useful setup step is a GEMINI.md in the project root. Gemini CLI reads it every turn, so keep it short and specific to this repository. Include the exact commands, folder conventions, and rules that are easy for an agent to get wrong in Nuxt.
# Nuxt project instructions
## Commands
- Install: npm install
- Dev: npm run dev
- Build: npm run build
- Lint: npm run lint
- Test: npm run test
- Typecheck: npm run typecheck
## Conventions
- Use file-based routing: pages/ for routes and server/api/ for API endpoints.
- Rely on Nuxt auto-imports. Do not manually import useState, useFetch, useRuntimeConfig, defineEventHandler, or ref.
- Put shared client state in composables/ and use useState with a unique key when state should persist across navigation.
- Server routes live in server/api/ and must use defineEventHandler from h3. Return plain objects or use createError for errors.
- Never access window, document, or localStorage during component setup; use onMounted, client-only, or import.meta.client.
- Read environment variables only through runtimeConfig, never process.env in client code.
- Run npm run test and npm run lint after each change. Run npm run build before finishing a larger task.A Nuxt-specific file like this prevents most repeated corrections. If you already have CONTRIBUTING.md or docs, point GEMINI.md to the two or three files that matter instead of copying everything.
If you are new to the workflow, the step-by-step guide to using Gemini CLI covers how the agent reads instructions and works with your repo; the project file above is what makes it Nuxt-aware.
A repeatable workflow: plan, edit, test, review
A reliable loop is: plan first, make one small change, run the relevant test command, review the diff. Ask Gemini CLI to state its plan before editing. Then tell it to implement only that slice. After it finishes, run npm run test, npm run lint, and optionally npm run build yourself or ask the agent to run them and fix failures. Review git diff before accepting.
Example prompts:
- “Create a new page at pages/orders/index.vue that lists orders from server/api/orders.get.ts. Use useFetch and show loading, error, and empty states.”
- “Add a server route server/api/orders/[id].get.ts that reads from server/data/orders.ts, returns one order, and throws createError with a 404 when missing. Add a matching Vitest test.”
- “Refactor the cart logic from components/CartPanel.vue into a composable composables/useCart.ts with add, remove, and total. Keep the component SSR-safe and use useState for cart persistence.”
- “Add validation to server/api/checkout.post.ts with zod. Return a 422 response with field errors and update the test file to cover invalid input.”
- “Fix the hydration mismatch on pages/products/[id].vue. Do not disable SSR; identify the source of the mismatch and apply the smallest fix.”
These prompts name a concrete path and the Nuxt API to use, which reduces wandering.
What Nuxt tasks to delegate and what to double-check
Nuxt tasks the agent handles well: creating pages and components with script setup, writing composables that use useState/useFetch, adding server routes with defineEventHandler, writing Vitest tests, extracting types, and updating existing code across multiple files.
Pitfalls specific to Nuxt where to watch it closely:
| Area | Common mistake | Instruction to give | | Auto-imports | It adds manual imports for useState, useFetch, useRuntimeConfig or ref. | Rely on Nuxt auto-imports; remove unused imports. | | Server routes | It returns a Response object or uses Node-only APIs where h3 helpers are simpler. | Use defineEventHandler and h3 helpers; return plain data or createError. | | SSR and hydration | It accesses window or document in setup, or generates random ids/dates in the template. | Keep browser APIs in onMounted or client-only; use useId() for ids. | | Shared state | It puts mutable state in composable module scope, leaking state between users or tests. | Use useState with a unique key and reset logic. | | Data fetching | It duplicates fetch logic instead of using useFetch/useAsyncData, losing SSR and caching. | Prefer useFetch/useAsyncData and set explicit keys. |
Review server routes especially for type shape: Nitro serializes returned values, so a Date or BigInt can behave differently than in a local unit test.
Verify Nuxt changes with Vitest and build
Use Vitest. For utilities and composables, plain Vitest is enough. For components and pages, use @nuxt/test-utils/runtime and mountSuspended or renderSuspended. For server routes, import the handler and call it with a mock event using createEvent from h3 or use setup from @nuxt/test-utils. Ask the agent to add a test beside the code it changes and to run npm run test -- --run or the script in package.json. After tests pass, run npm run lint and npm run build to catch auto-import, SSR, and type issues. Tell the agent to fix all warnings it introduced, not just errors.
Parallel Nuxt work with AgentVera
When one Gemini CLI session is not enough, AgentVera can run several coding agents in parallel, each in its own git worktree, so Nuxt page, composable, and API work stay isolated. Automatic code review from a second model catches auto-import or SSR mistakes before they reach main. Checkpoints let you undo a bad turn, and token budgets stop runaway commands in a large Nuxt repo. This matters for Nuxt because parallel work on routes and client state often conflicts if not isolated.
Final notes for Nuxt + Gemini CLI
Gemini CLI becomes much more effective on Nuxt when the project’s conventions are explicit in GEMINI.md and each prompt targets one route, composable, or test. Review diffs with Nuxt’s auto-import and SSR rules in mind, and use Vitest plus build as your safety net. With that workflow, the agent handles most routine Nuxt work reliably and leaves you to review the architectural decisions.