Claude Code Nuxt: a practical setup for Nuxt developers

Claude Code is a strong fit for Nuxt because it can operate directly on the file-based router, server routes, composables and Nitro/Vitest tooling. Start claude in the project folder after recording Nuxt-specific conventions in CLAUDE.md. For general agent workflow, see Claude Code best practices: a practical checklist.

Why Claude Code fits Nuxt projects

Nuxt is convention-driven: a file path determines a route or a server endpoint, and many Vue and Nuxt APIs are auto-imported. Claude Code reads the project tree and can follow those conventions when they are written down. It can change a page, its composable and its server route in the same task, then run the commands Nuxt developers already use. Unlike a chat-only assistant, the agent operates in a terminal: it can run the dev server, typechecker, linter and Vitest, read their output and correct the code until the project is green. That makes it practical for real Nuxt work, not just snippets. Because Nuxt uses Nitro for server routes, the agent can also verify handler behavior with test utilities without leaving the repo.

Prepare a Nuxt repo for the agent

The most important file is CLAUDE.md at the project root. Keep it short and specific. It should not explain Nuxt from scratch; it should record the commands and conventions this repository actually uses. Include package manager commands, build/test/lint/typecheck commands, the locations of pages, components, composables, server routes, server utilities and tests, and rules that prevent Nuxt-specific mistakes. If your project uses srcDir, app/ directory, custom layers or a monorepo layout, write that down too. Also record any environment variables used by Nitro handlers and whether they come from runtimeConfig or .env; this avoids process.env mistakes later.

# Nuxt project notes

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

## Conventions
- Do not add explicit imports for auto-imported Vue and Nuxt APIs.
- Routes live in pages/; use kebab-case file names.
- Server endpoints live in server/api/ and are exposed under /api/<file>.
- Shared server utilities live in server/utils/.
- Reusable client logic goes in composables/ with use-prefixed names.
- Tests live next to code in tests/ or __tests__; run with Vitest.

## Rules
- Keep Nitro handlers as async functions that return JSON or set the correct status.
- Use useFetch or $fetch for data loading in components, not axios.
- Do not edit generated files in .nuxt/, .output/ or node_modules/.
- Run pnpm typecheck and pnpm test after changes to server routes or composables.

Keep the file compact. The table below summarizes the main Nuxt surfaces the agent needs to understand.

| Path | Purpose | Agent notes | | pages/ | File-based routes | Each file maps to a route; use kebab-case names | | server/api/ | Nitro HTTP endpoints | Each file maps to /api/…; return JSON and status codes | | server/utils/ | Shared server helpers | Auto-imported in server code | | composables/ | Reusable client logic | Use-prefixed names, auto-imported | | tests/ | Vitest tests | Run with pnpm test |

A safe working loop for Nuxt edits

Work in small steps and ask for a plan before larger refactors. Start from a clean working tree. Give the agent one task at a time. After each change, have it run the relevant verification commands, then review the diff with git diff. If it touched server routes or composables, require pnpm typecheck and pnpm test. If it changed pages or components, also run pnpm lint or the dev server when needed. Plan mode is useful here; see Claude Code plan mode: plan first, then let it build. Ask for a short plan when the change touches both pages and server code; this surfaces route naming and validation choices before code is written.

Example prompts for typical Nuxt tasks:

• Add a POST /api/contact server route that validates a name and message, returns 201 on success and 422 with field errors. Then add pages/contact.vue using useFetch to submit the form and show validation errors.
• Create a useCart composable with a reactive items array, a total computed and localStorage persistence. Write Vitest tests for add, remove and total.
• Convert pages/users/[id].vue to use useFetch with the route param, add loading and error states, and keep the page SSR-safe.
• Move repeated error handling into server/utils/errors.ts and update three existing server routes to use it, then run typecheck and tests.
• Review the diff from the last change for Nuxt-specific issues: auto-imports, SSR/client hydration mismatches, Nitro handler status codes and generated files.

Keep prompts atomic. If the agent starts changing unrelated files, stop and narrow the task. Use git status to see which files it touched before accepting the result.

What Claude Code handles well and where it slips in Nuxt

Claude Code handles several Nuxt tasks well: adding CRUD-style endpoints under server/api, creating pages and nested routes, writing composables and their Vitest tests, and refactoring repeated logic into server utilities. It can also convert an existing page from a local fetch call to useFetch while preserving loading and error states. With documented layer paths, it can work in Nuxt layers and modules as well. For larger refactors, it can split a monolith page into composables and server utilities, but require tests before it starts moving files.

Watch these Nuxt-specific pitfalls:

• Auto-imports: the agent may add explicit imports from ‘vue’ or ‘#imports’ even when Nuxt auto-imports them. This is not always harmful but creates noise; tell it to follow the conventions.
• SSR/client boundary: the agent may use window or document at the top level of setup, causing hydration errors. Ask it to guard browser-only code in onMounted or client-only checks.
• Nitro handlers: it may return a plain object without setting the right status code, or use process.env instead of runtime config. Explicitly request 201/422/500 behavior.
• Route and middleware logic: it may put auth checks in the page component instead of route middleware. Point it to the correct pattern.
• Generated folders: it may try to edit .nuxt, .output or node_modules. Rule those out in CLAUDE.md.

Testing Nuxt changes with Vitest and typecheck

Make verification part of the prompt. Use Vitest and @nuxt/test-utils for component and composable tests. For server routes, call them with $fetch inside tests or use the Nuxt test context. After every server route or composable change, run pnpm typecheck. After page changes, run pnpm lint. Before merging, run pnpm build once to catch Nitro or SSR issues that dev mode misses. Describe the expected status codes and response shape before implementation, so the agent can verify against them. Ask the agent to read the command output and not just report success from memory. If @nuxt/test-utils is configured, ask for mounted component tests rather than isolated unit tests for composables that depend on Nuxt context.

Running multiple Nuxt agents in parallel with AgentVera

When a Nuxt project has several workstreams, AgentVera can run multiple Claude Code agents in parallel without file conflicts. Each agent gets its own git worktree, so one can edit pages while another changes server routes and a third writes composable tests. When an agent finishes a turn, a second model reviews the code and links findings to file:line, which helps catch Nuxt-specific problems like SSR hydration mismatches or Nitro handler errors before merge. Checkpoints let you undo a bad turn and replay the session, and the approvals queue keeps waiting agents visible until you allow the next step. For more on running parallel Claude Code agents, see How to run multiple Claude Code agents in parallel.

Final practice

Claude Code is most effective on Nuxt when the repository’s conventions are explicit, changes are small, and tests are run after every step. Keep CLAUDE.md current, watch auto-imports and SSR boundaries, and use a separate git worktree if you run more than one agent. That turns the agent from a snippet generator into a dependable pair of hands for real Nuxt work.