# GitHub Copilot CLI for Nuxt projects: practical guide

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

Use GitHub Copilot CLI on Nuxt projects. Learn setup, prompts for file-based routing, server routes, composables, and Vitest, plus pitfalls and verification.

**In short:**

- Put Nuxt-specific rules and commands in .github/copilot-instructions.md so the agent uses file-based routing and Nitro correctly.
- Use short, test-driven prompts for composables, server routes, and pages; run Vitest after each change.
- Review diffs for auto-imports, server/client split, and payload mismatches because Copilot may guess wrong.

GitHub Copilot CLI is the coding agent you start with `copilot` in a Nuxt project folder and point at .github/copilot-instructions.md or AGENTS.md. In a Nuxt app, that agent works best when you give it explicit rules for file-based routing, server routes, composables, Vitest, and Nitro. This guide shows how to set that up, run a focused loop, and catch the Nuxt-specific mistakes that can slip through.

## Where Copilot CLI saves time in Nuxt projects

Nuxt splits concerns across `app/` (or the root `pages/`), `server/`, and `composables/`, with Nitro handling the server side and Vue providing auto-imports. A terminal-based agent like [GitHub Copilot CLI](/en/agents/copilot-cli/) can read those files, run `npx nuxi typecheck` and `vitest run`, and edit both client and server code in one session without switching tools. That matters for tasks that touch a page, a server API route, and a shared type at the same time. When the instruction file defines the Nuxt conventions, the agent is less likely to invent wrong imports or place server-only code in a client bundle. The step-by-step guide at [How to use GitHub Copilot CLI: a step-by-step guide](/en/blog/how-to-use-copilot-cli/) shows the general workflow that you can adapt to Nuxt.

## Teach Copilot CLI your Nuxt project rules

Create `.github/copilot-instructions.md` in the repository root (or use `AGENTS.md` if you already have one). Keep it short and concrete: commands, folder conventions, and rules that prevent Nuxt-specific mistakes. The file should tell the agent how to run tests, type checks, lint, and build, and where it may and may not place code.

Example:

```markdown
# Nuxt project instructions

Commands:
- install: npm install
- dev: npm run dev
- test: npx vitest run
- lint: npx eslint .
- typecheck: npx nuxi typecheck
- build: npm run build

Folder conventions:
- app/pages/ for file-based routes
- app/components/ for Vue components
- composables/ for auto-imported shared logic
- server/api/ for Nitro API routes
- server/utils/ for server-only helpers

Rules:
- Use Nuxt auto-imports; do not import ref, computed, useFetch, or defineEventHandler manually.
- Server routes return data, never JSX or HTML; use createError for errors.
- Keep server-only code out of composables that run on the client.
- Add or update a Vitest test when changing composables, server routes, or pages.
- Run `npx vitest run` and `npx nuxi typecheck` before finishing a task.
```

Adjust the paths if your Nuxt project uses `pages/`, `components/`, or `server/` in the root. The important part is that the agent sees the structure you actually use.

## A daily loop: plan, edit, test, review

Use the same loop you would with a capable but junior colleague: state the exact outcome, let the agent plan, make one small change, run the narrow tests, and inspect the diff before moving on. Do not ask for a whole feature in one prompt if it spans a page, a server route, and a composable; split it by layer or by test.

Start with `copilot` in the project folder and ask for a plan before edits. Then use prompts like:

- Add a `useCart` composable in `composables/useCart.ts` that stores items in a `ref`, computes the total with `computed`, and persists to `localStorage` only on the client. Add `composables/useCart.test.ts` with Vitest and Nuxt test environment.
- Create `server/api/products/[id].get.ts` that returns a product by id from a `products.json` file in `server/data/`, or throws `createError({ statusCode: 404, statusMessage: 'Product not found' })`. Add a server route test with `$fetch`.
- On `app/pages/checkout.vue`, replace the hard-coded VAT with `useRuntimeConfig().public.vatRate`. Update `nuxt.config.ts` to define the public runtime config and add a check to the page test.
- Refactor `server/api/order.post.ts` to validate the body with `zod` and return `{ orderId }`. If `zod` is not installed, use `h3`'s `readBody` and manual checks. Run typecheck and the route test.
- Create a simple `app/components/PriceTag.vue` that formats a number with `Intl.NumberFormat` and takes a `currency` prop. Add a component test that mounts it and checks the formatted output.

After each prompt, review the generated changes with `git diff`. Run the relevant test file, then the full suite. A change to a Nitro route can affect the client, so the agent should run `npx nuxi typecheck` before you accept it.

## Where Copilot CLI is strong, and the Nuxt traps to watch

| Task | Good prompt | Verify with |
|---|---|---|
| Server API route | `Create server/api/health.get.ts that returns { status: 'ok' } and add a test.` | `npx vitest run server/api/health.test.ts` |
| Composables | `Extract a usePagination composable from the listing page and test it.` | `npx vitest run composables/usePagination.test.ts` |
| Page refactor | `Refactor app/pages/[slug].vue to fetch data with useAsyncData and render a not-found state.` | `npx nuxi typecheck` and manual `npm run dev` |
| Nitro config | `Add a public runtime config value and consume it in app.vue.` | `npm run build` and grep for `useRuntimeConfig` |

The agent is usually reliable for self-contained server routes, small composables, and tests that follow the project’s existing patterns. Watch closely when it changes:

- Auto-imports: it may add `import { ref } from 'vue'` even though Nuxt auto-imports `ref`, which is harmless but inconsistent, or it may assume a custom composable is auto-imported when it is not.
- Server/client split: it may place `process.env` or Node-only imports in a composable that runs in the browser, or use `window` in a Nitro handler.
- `useFetch` and `useAsyncData`: it may not respect `pick`, `transform`, or the difference between server and client payloads, leading to hydration mismatches.
- Route params and middleware: it can create a dynamic route but forget `validate` or misname the file in `server/api/[id].get.ts` versus `server/api/[id]/index.get.ts`.
- Nitro imports: it may import `defineEventHandler` from `h3` instead of relying on the auto-import, or use `event.node.req` when `getQuery` is clearer.

## Verifying Nuxt changes before you accept them

Make the agent treat a change as done only after the relevant checks pass. In the instruction file, require:

- `npx vitest run` for unit and route tests
- `npx nuxi typecheck` for type errors across server and client
- `npx eslint .` for style and obvious mistakes
- `npm run build` for real Nitro and Nuxt builds
- `git diff` review before any commit

For UI changes that involve interaction or browser-only behavior, ask the agent to run `npm run dev` and then use AI agent browser testing to let the agent check the app in a real browser, as described in [AI agent browser testing: let the agent check your app](/en/blog/ai-agent-browser-testing/). That catches issues like a missing `client` guard in a composable or an incorrect `useFetch` response that only appears at runtime. When the agent cannot run the browser, ask it to at least generate a focused Vitest test with `@nuxt/test-utils` and mount the component.

## Parallel Nuxt work with AgentVera

AgentVera runs several coding agents in parallel, each in its own terminal panel. You can give each agent its own git worktree so one Nuxt change does not overwrite another’s files. Automatic code review flags Nuxt-specific issues such as client/server leaks at file:line, and checkpoints let you undo a turn and replay it. Token budgets cap each agent so one runaway search does not block the others. This is useful when one agent works on server/api routes while another refactors composables, because the isolated worktrees and review pass keep Nitro mistakes from reaching the branch.

## Keep Copilot CLI focused on one Nuxt layer at a time

GitHub Copilot CLI becomes a reliable Nuxt pair when the project instruction file is explicit, the prompts stay small and test-driven, and every diff is reviewed at the server/client boundary. Keep the agent to one layer at a time, require `npx vitest run` and `npx nuxi typecheck`, and split parallel work with worktrees when you scale beyond a single thread. With that setup, the agent spends less time guessing and more time shipping Nitro routes, composables, and pages that actually typecheck and test green.

## Frequently asked questions

**How do I start GitHub Copilot CLI in a Nuxt project?** Run copilot in the project root and point it at .github/copilot-instructions.md or AGENTS.md. The agent reads the file, inspects your Nuxt source folders, and suggests a first change. Keep Node, the package manager, and the dev server ready before starting.

**What should be in .github/copilot-instructions.md for Nuxt?** Include build, test, lint and typecheck commands, folder conventions for app/, server/, and composables/, and rules like using Nuxt auto-imports and createError in Nitro routes. Keep it short so the agent follows it consistently.

**Can GitHub Copilot CLI write Nuxt server routes and composables?** Yes, for focused tasks with explicit paths and expected behavior. Ask it to create a file under server/api/ or composables/, then verify the result with npx vitest run and npx nuxi typecheck. Review for auto-import mistakes and server/client leaks.

**How do I verify changes made by GitHub Copilot CLI in Nuxt?** Run npx vitest run, npx nuxi typecheck, npx eslint ., and npm run build. Check git diff for misplaced server-only code or manual Vue imports. For UI changes, run npm run dev and test in a browser.

---

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