Codex Nuxt: Practical Guide for Nuxt Developers

Codex is a coding agent you start with codex in the project folder. In a Nuxt project, it works best when it reads a strict AGENTS.md, makes small file-level changes, and verifies them with Nuxt’s own test, typecheck, and build commands. This guide covers the practical loop, useful prompts, and Nuxt-specific failure modes to watch.

Why Codex fits Nuxt projects

Nuxt’s structure is largely encoded in file paths: pages under pages/ become routes, handlers under server/api/ become HTTP endpoints, exported functions from composables/ become auto-imported shared logic, and Nitro handles server bundling. That means Codex can be given file-level prompts like add a page or add an endpoint without a long architecture explanation. The agent can read the existing tree and follow the same naming patterns, which reduces the need to describe the whole app in every prompt.

The same structure creates hidden constraints. Auto-imports obscure dependencies, server-only modules must stay out of the client bundle, route file names determine both path and HTTP method, and Nitro has its own server module graph. A single-file edit can look correct but fail only when the full Nuxt build runs. Codex therefore needs explicit project rules and a verification step that runs the same commands as CI. Without that, it will confidently add a server import to a Vue component and not notice until the build breaks.

Configure the repo with AGENTS.md

Keep an AGENTS.md file in the repository root. Codex reads it as project instructions, so write it as a set of commands and folder contracts, not as generic advice. Include the exact scripts from your package manager, the Nuxt directories you use, and rules that protect auto-import and server boundaries. The example below is a minimal version; adjust the package manager and test script to match your project.

# AGENTS.md

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

## Nuxt conventions
- Pages live in `pages/`; each file creates a route. Dynamic segments use `[id].vue`, and directories create nested routes.
- API handlers live in `server/api/` and use method suffixes: `*.get.ts`, `*.post.ts`, etc. Export `defineEventHandler`.
- Browser-side shared logic belongs in `composables/`; exported functions are auto-imported.
- Server-only helpers belong in `server/utils/` and must never be imported from client code.
- Components and composables use `useFetch` or `$fetch` for API calls.

## Rules
- Make one focused change at a time.
- Do not add manual imports for Nuxt, Vue, or Nitro auto-imports.
- Run `pnpm test` and `pnpm typecheck` before finishing.
- Run `pnpm build` before finishing server route, Nitro config, or import boundary changes.
- If a test or build fails, report the exact command output before trying a fix.

Keep the file short enough to be followed. If a convention changes, update AGENTS.md before asking Codex to edit related code. Do not put credentials or environment-specific values in the file; use environment variables instead. For a broader introduction to the CLI, see how to use Codex CLI; details about the agent are in Codex.

A practical Codex loop for Nuxt changes

The most reliable loop is plan, small edit, verify, review. Ask Codex to name the files it intends to change before editing. Then let it change one route, one composable, or one component set. Run the relevant commands from AGENTS.md after each turn and review git diff yourself, especially for files you did not expect to change.

Example prompts for typical Nuxt tasks:

• Add pages/settings.vue that loads /api/user with useFetch, shows a loading state, and renders an error message on failure.
• Create server/api/user.get.ts that reads the current user from server/utils/auth.ts and returns 401 when no session exists. Add a Vitest test for both cases.
• Extract the duplicated cart logic from pages/cart.vue and components/CartButton.vue into composables/useCart.ts, then update both components to use it.
• Update the default layout so the navigation highlights the active route and closes the mobile menu on route change.
• Run pnpm test, then fix only the failing tests in tests/orders.spec.ts without changing the test assertions.

Each prompt names a concrete file and observable behavior. After the edit, run git diff --stat before reading the full diff. In Nuxt, an agent may accidentally create a new page in pages/ when you asked to edit a component; the stat line reveals that immediately. If a change touches too many files, ask the agent to revert and split the task into smaller pieces.

Nuxt tasks Codex handles and pitfalls to watch

Codex handles the most valuable Nuxt work well: creating pages, adding server API handlers, extracting composables, updating Vue templates, and writing Vitest tests after the code exists. It is also good at migrating repeated fetch logic into useFetch or useAsyncData and adding defineEventHandler routes from a description.

Watch closely around the Nuxt-specific areas in the table below.

Most Codex-introduced Nuxt bugs fall into these five categories. Checking the diff for them is faster than debugging after a failed production build.

Verify Nuxt changes before merge

Make Codex run the exact commands from AGENTS.md. For server routes, prefer a Vitest test that calls the route through the Nuxt test context or $fetch; this exercises routing, not just the handler function. For composables, a plain Vitest test can verify state transitions. For components, use @nuxt/test-utils and mountSuspended when you need Nuxt runtime behavior such as useFetch or route middleware.

A practical verification sequence is pnpm test after code changes, pnpm typecheck after TypeScript changes, pnpm lint for formatting and rules, and pnpm build before merging changes to server routes, Nitro config, or import boundaries. Ask Codex to include command output when a check fails; otherwise the next edit often repeats the same mistake.

Review the diff for unexpected files. Nuxt auto-imports mean a change in one composable can affect many pages without those files appearing in the diff. If a test fails and the failed assertion seems unrelated, ask Codex to trace which auto-imported module changed by checking git show on the composable directory. Also verify that new tests actually run and are not skipped accidentally.

Run parallel agents with AgentVera

For larger Nuxt features, you can run multiple Codex agents in parallel with AgentVera, a desktop app that runs real CLI agents side by side. The parallel git worktree support matters because Nuxt pages and composables often share state, so each agent working in its own worktree avoids overwrite conflicts. Automatic code review, where a second model checks code at the end of a turn and reports file:line findings, catches auto-import misuses and server boundary mistakes that a single agent misses; see AI code review. Checkpoints let you undo a bad server route change and replay the session, which is valuable when Nitro bundling fails after a plausible-looking edit. Token budgets keep runaway full-build loops from consuming the whole day’s quota.

Bottom line

Treat Codex as a file-level developer that needs a contract. With a concise AGENTS.md, small focused prompts, and the same verification commands as CI, it can create Nuxt pages, API routes, and composables reliably. Check the diff for auto-import and server boundary mistakes, run the build before merging, and use AgentVera when you need parallel work with review and rollback.