# Claude Code Nuxt: a practical setup for Nuxt developers

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

Learn how to configure Claude Code for Nuxt projects: CLAUDE.md rules, server routes, composables, Vitest loops, and safer agent workflows.

**In short:**

- Claude Code handles Nuxt file routes, server endpoints, composables and Vitest tests best when CLAUDE.md records the project conventions.
- Work in small steps: ask for a plan, run typecheck and tests after each change, then review the diff.
- Watch auto-imports, SSR/client boundaries and Nitro handler responses as the main Nuxt-specific failure points.

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](/en/blog/claude-code-best-practices/).

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

```markdown
# 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](/en/blog/claude-code-plan-mode/). 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](/en/blog/run-multiple-claude-code-agents/).

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

## Frequently asked questions

**How do I use Claude Code with a Nuxt project?** Start claude in your Nuxt project folder. Put commands and Nuxt conventions in CLAUDE.md so the agent uses the right file-based routing, server routes, and composable patterns.

**What should I put in CLAUDE.md for Nuxt?** Include package manager commands, build/test/lint commands, and rules for auto-imports, pages/, server/api/, composables/ and tests. Explicitly tell the agent not to edit generated folders like .nuxt or .output.

**Can Claude Code create or edit Nuxt server routes?** Yes. It can modify server/api files and Nitro handlers. Ask it to return correct status codes and validation errors, then verify with Vitest or pnpm typecheck.

**Does Claude Code work with Nuxt 3 and Nitro?** It works with the current Nuxt/Nitro toolchain if the project commands are in CLAUDE.md. The agent reads the file tree and follows the conventions you specify.

---

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