Cursor Agent Nuxt: Practical Setup and Workflow Guide

Cursor Agent is the terminal coding agent from Cursor, started with cursor-agent in your project folder. In a Nuxt app it can add pages, composables, server routes, and tests, but the quality depends on the Nuxt-specific context you provide. This guide covers setup, prompts, testing, and pitfalls for Nuxt. See Cursor Agent for the agent itself.

Why Cursor Agent fits Nuxt work

Nuxt is convention-heavy: pages, components, composables, and server routes work because the framework auto-imports and resolves files from known directories. Cursor Agent operates well in that structure because it reads the repository, uses your package scripts, and can keep changes scoped to the right folder. For example, a single prompt can add server/api/orders/[id].get.ts, a composables/useOrder.ts, and the matching Vitest test. The advantage is not broad code generation, but consistency of Nuxt-specific details: Nitro handler signatures, typed useFetch wrappers, createError usage, and test setup. Document those once and the agent repeats them across tasks. In practice this means less time correcting auto-import mistakes and more time reviewing behavior.

Setting up a Nuxt project for Cursor Agent

Create AGENTS.md at the root and keep it focused on commands, folder boundaries, and rules that Nuxt does not already enforce. If your repository already has standardized scripts, reuse them. Here is a short example:

# AGENTS.md

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

## Nuxt conventions
- Pages live in `pages/`; use file-based routing. Do not create manual route config.
- Server API routes live in `server/api/`; one handler per file.
- Composables live in `composables/` and must export a `use*` function.
- Shared validation helpers go in `shared/` so client and server can import them.

## Rules
- Do not import auto-imported Vue or Nuxt APIs explicitly.
- Server handlers must use `defineEventHandler` and return plain JSON or a `Response`.
- Use `createError` for HTTP errors, not thrown strings.
- Run `pnpm test` after edits that touch server routes or composables.

For topic-specific rules, you can split this into .cursor/rules/nuxt.md or .cursor/rules/nitro.md; Cursor Agent reads both AGENTS.md and .cursor/rules. Keep rules actionable and negative where possible: “do not import auto-imported APIs” is more useful than a long explanation of auto-imports. Also include the package manager and test runner exactly as used in CI, so the agent runs the same commands you do. Keep the file short; the agent should not have to parse a long architecture document for every task. If you use nuxi commands, list them exactly, because the agent will run the scripts from package.json rather than guessing. Also tell the agent where shared types live, such as shared/types.ts, because server routes and composables often share request and response interfaces.

A working loop for Nuxt tasks

Use a plan, small step, test, and diff review loop. Start with an issue-style prompt that names the file or route, the expected behavior, and the command to verify. After the agent edits, run the verification command yourself or ask the agent to run it, then review git diff before moving to the next step. In Nuxt this loop matters because auto-import and file-based routing can hide mistakes until the dev server or build fails. Before starting, inspect git status to know the baseline; after the agent finishes, use git diff --stat to see the blast radius.

Example prompts for typical Nuxt tasks:

• Add a server route GET /api/products in server/api/products.get.ts that returns a list from useProductStore(); keep it JSON only and add a Vitest test at server/api/products.get.spec.ts.
• Create a composable useCartCount() in composables/useCartCount.ts that tracks the number of items in the cart store and stays reactive; do not import ref or computed explicitly.
• Refactor the checkout flow to use useFetch with typed responses; update pages/checkout.vue and add a test for the successful response path.
• Fix the failing test in tests/checkout.spec.ts only; run pnpm test and adjust the code, not the assertion, unless the assertion is clearly wrong.
• Add input validation with zod to server/api/orders.post.ts and reject invalid payloads with 400 using createError.

These prompts are specific because they name the file and the expected change. The agent still needs the AGENTS.md conventions to know what not to do. If you are new to the terminal workflow, How to use Cursor CLI: a step-by-step guide explains the same loop in more detail.

Where Cursor Agent helps and where to watch closely

The agent is strongest with scoped, file-level changes. It is less reliable with cross-cutting Nuxt changes because the framework’s auto-imports and Nitro server layer can produce errors only at build or runtime. Watch closely when it modifies nuxt.config.ts, route middleware, or plugins; these have global effects. Also be careful when the agent edits app.vue, plugins/, or middleware/ because those run globally in the Nuxt app; a bad plugin can break every route.

One common failure is adding an explicit import for something Nuxt auto-imports, which makes code inconsistent but sometimes still passes. Another is creating server routes that assume browser APIs like window; remind the agent that server/ runs in Nitro, not in the Vue client. Also check that server routes use getRouterParam instead of hand-parsing query strings.

Testing and verification in Nuxt

Treat agent edits as candidates, not final code. Run pnpm test to exercise Vitest, pnpm lint for style and import rules, pnpm typecheck if available, and pnpm build before merging. The agent can run these commands, but you should inspect the diff for Nuxt-specific mistakes. Use git diff -- server/ composables/ pages/ to narrow review. For server routes, test both success and error cases; Nuxt server handlers often pass unit tests but fail integration when the Nitro runtime resolves path params differently. Use $fetch from @nuxt/test-utils to call the handler through the Nitro test environment where possible, because a unit test that imports the handler directly can miss Nitro-specific behavior. If the agent changed a page, open the route in the dev server and click through navigation to confirm the file-based route resolves.

Running several agents on one Nuxt project with AgentVera

AgentVera is a desktop app that runs coding agents’ real command line tools side by side in one window, each in its own real terminal panel. For Nuxt, the strongest fit is parallel work in separate git worktrees: one agent can edit server/ while another builds a composable without overwriting files. Automatic code review links findings to file:line, which helps catch broken auto-imports. Checkpoints let you undo a turn, and token budgets keep a long Nitro refactor from exhausting the day’s usage. See Best tools to run AI coding agents in parallel (2026) for the parallel workflow.

Wrap-up

With a short AGENTS.md, scoped prompts, and a test-first loop, Cursor Agent can handle a large share of daily Nuxt work: server routes, composables, page-level changes, and Vitest coverage. Keep the review focused on Nuxt-specific seams: auto-imports, Nitro handlers, route params, and build-time errors. Once the loop is stable, parallel agents can accelerate feature work without turning the repository into a merge problem.