# Codex Nuxt: Practical Guide for Nuxt Developers

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

Learn how to use Codex in a Nuxt project: set up AGENTS.md, run server routes and composables, test with Vitest, and avoid Nuxt-specific pitfalls.

**In short:**

- Codex handles Nuxt pages, server routes, and composables well when AGENTS.md defines exact commands and folder conventions.
- Use small file-level prompts, run pnpm test, typecheck, and build after each change, and review the diff for Nuxt-specific import issues.
- Watch auto-imports, server/client boundaries, and Nitro bundling, because those are the most common sources of agent-introduced Nuxt failures.

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.

```markdown
# 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](/en/blog/how-to-use-codex-cli/); details about the agent are in [Codex](/en/agents/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.

| Nuxt area | What to check in the diff |
|-----------|---------------------------|
| Auto-imports | Codex may add explicit imports from `vue` or `nuxt/app` instead of relying on Nuxt auto-imports. Usually harmless, but check for duplicate imports and client-only APIs in server files. |
| Server/client boundary | A component may import from `server/utils/`, or a server route may import a browser-only module. Keep server-only code under `server/`. |
| File-based routing | Dynamic routes must use `[param].vue`, and nested routes need `pages/parent/index.vue` plus `pages/parent/[id].vue`. The agent sometimes places a route at the wrong depth or uses query params instead of path params. |
| Event handler context | Server routes run in Nitro, not Vue setup. `useFetch`, `useAsyncData`, and lifecycle hooks belong in components or composables, not in `defineEventHandler` bodies. |
| Nitro bundling | Node built-ins and server-only dependencies may typecheck but fail in production if not handled through Nitro’s server build. Verify with `pnpm build`. |

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](/en/blog/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.

## Frequently asked questions

**How do I start Codex in a Nuxt project?** Run codex in the project root after adding an AGENTS.md file with your build, test, lint, and Nuxt folder conventions. Codex reads that file at startup and uses it as project instructions.

**Can Codex create Nuxt server API routes?** Yes. Ask it to add a file under server/api/, export a defineEventHandler, and include method suffixes such as *.get.ts when needed. Then have it add a Vitest test that calls the route through the Nuxt test context.

**Does Codex respect Nuxt auto-imports?** It usually follows AGENTS.md if you state that Nuxt auto-imports composables and server handlers, but it may still add explicit imports. Review the diff for imports from vue, nuxt/app, or server/utils/ that break your conventions.

**How can I keep Codex from breaking a Nuxt build?** Define exact commands in AGENTS.md, require Codex to run pnpm test, pnpm typecheck, and pnpm build after changes, keep tasks small, and check diffs for server/client boundary mistakes.

---

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