GitHub Copilot CLI for Nuxt projects: practical guide

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 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 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:

# 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

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. 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.