# Gemini CLI with Nuxt: A Practical Guide for Developers

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

Learn how to use Gemini CLI in a Nuxt project: setup GEMINI.md, prompts for pages, server routes, composables, and testing with Vitest.

**In short:**

- Set up GEMINI.md with Nuxt-specific build, test, lint commands and auto-import/SSR rules so Gemini CLI respects the project conventions.
- Use plan-first, small prompts for pages, server routes, composables, and tests; always review the diff for auto-import and hydration mistakes.
- Run several agents in separate git worktrees with AgentVera to parallelize Nuxt features without overwriting files.

[Gemini CLI](/en/agents/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.

```markdown
# 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](/en/blog/how-to-use-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](/en/blog/ai-coding-agent-orchestration/) 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.

## Frequently asked questions

**How do I start Gemini CLI in a Nuxt project?** Open a terminal in your Nuxt project folder and run gemini. It reads GEMINI.md from the project root, so add Nuxt-specific commands and conventions before starting larger tasks.

**What should be in GEMINI.md for Nuxt?** Include npm commands for dev, build, lint, test, and typecheck. Add folder rules for pages/, components/, composables/, and server/api/, plus reminders about auto-imports, SSR safety, and runtimeConfig.

**Can Gemini CLI create Nuxt server routes and composables?** Yes. Give it a path such as server/api/orders.get.ts or composables/useCart.ts and the expected behavior. It can also write matching Vitest tests, but review the output for correct h3 helpers and auto-imports.

**How do I prevent Gemini CLI from breaking Nuxt auto-imports or SSR?** State in GEMINI.md that auto-imported APIs must not be imported manually and that browser APIs belong in onMounted or client-only. After each change, run tests and build, then review the diff for import and hydration mistakes.

---

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