opencode Nuxt: a practical development guide for agents

opencode is a terminal coding agent that works well in a Nuxt project when you start it in the project root, keep Nuxt-specific rules in AGENTS.md, and make it work in short test-driven steps. It can add pages, server routes, composables, and tests, but you need to verify Nitro behavior and SSR hydration carefully. This guide shows a practical setup and loop for daily Nuxt development with opencode.

What makes opencode a good fit for Nuxt

Nuxt’s file-based routing and conventions give a coding agent a predictable map of the project. opencode can read pages/, server/, and composables/, then create files that fit those conventions without a lot of back-and-forth. It also runs commands such as pnpm test, pnpm build, and pnpm lint in the project terminal, so it can see the same errors a developer sees. The agent can reason across SFCs, Nitro handlers, and Vitest tests in one session. In practice this means less time writing boilerplate and more time reviewing the actual logic.

Configure AGENTS.md for Nuxt

The most important setup step is a concise AGENTS.md in the project root. opencode reads project instructions from that file on startup. For a broader setup walkthrough, see How to use opencode: a step-by-step guide. Keep the file specific to your Nuxt project: declare the package manager, the exact commands for dev, build, lint, typecheck, and test, the folder conventions, and the rules the agent must not break. Avoid walls of text; the agent should be able to scan it quickly.

Here is a short example that works for many Nuxt 3 projects:

# AGENTS.md

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

## Folder conventions
- Pages live in `pages/`; file names become routes.
- API handlers live in `server/api/`.
- Shared server utilities live in `server/utils/`.
- Reusable Vue logic lives in `composables/` and must start with `use`.
- App-wide types live in `types/`.

## Nuxt rules
- Auto-imports are enabled: do not add manual imports for Nuxt APIs, Vue APIs, or project composables.
- Use `useFetch` or `$fetch` for data fetching; do not add axios.
- Server routes must use `defineEventHandler` and should return typed JSON.
- `server/` code runs on Nitro and must not import Vue components.
- Add a Vitest test next to every new server route or composable.
- Do not change `nuxt.config.ts` without asking first.

This gives opencode enough context to avoid the most common Nuxt-specific mistakes: manual imports in auto-imported code, client-only code in server routes, and ad-hoc changes to the Nuxt config.

A repeatable Nuxt working loop

Use a tight loop: give one small task, let opencode make the change, run the tests and build, then review git diff. Do not ask for a full feature at once. This keeps the agent inside the Nuxt mental model and makes review easier.

Example prompts for common Nuxt work:

• ‘Add a server route /api/health that returns { ok: true } and a Vitest test for it using nuxt/test-utils.’
• ‘Create a useUser composable that wraps useFetch('/api/auth/me') and returns user, pending, and error, with a unit test.’
• ‘In pages/teams/index.vue, replace the static team list with useFetch('/api/teams'), keep loading and error states, and add an empty state.’
• ‘Add Zod validation to the existing server/api/tasks.post.ts and return a typed 400 error response when validation fails.’
• ‘Refactor pages/checkout.vue into smaller components under components/checkout/, then run pnpm lint and pnpm test and fix any issues.’

After each prompt, have opencode run the relevant commands and read the output. Then review the diff yourself. Nuxt’s DX makes this loop fast because the agent can start the dev server and use HMR in the terminal.

Where opencode shines and where to double-check

opencode is usually reliable for server routes, composables with useFetch or useState, simple page and component work, and adding tests. It can also update types and move logic between files. The table below summarizes the areas where it helps most and the specific pitfalls to review.

The most common Nuxt-specific pitfalls are treatment of auto-imports, server versus client environment, SSR hydration mismatches, and Nitro middleware order. Always review changes in server/ for accidental use of browser APIs, and check pages/ for missing definePageMeta or useHead calls.

Verify changes with Vitest and pnpm build

The fastest verification path is to ask opencode to run the project’s own commands after each change: pnpm test, pnpm build, pnpm lint, and pnpm typecheck. Vitest is the default test runner in Nuxt projects, and nuxt/test-utils lets you test server routes and components without much setup. For server routes, prefer a test that calls the handler through $fetch against a dev server or uses createTest from nuxt/test-utils.

When reviewing the agent’s work, do not trust a green test alone. Run pnpm build because it catches SSR and static generation issues that unit tests miss. For pages that fetch data, check both client and server rendering if possible. Ask opencode to paste the relevant terminal output when a command fails, then let it fix the issue in the same session. This keeps the loop fast and grounded in the actual Nuxt toolchain.

Run parallel Nuxt agents 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 terminal panel. For Nuxt work, the most useful parts are that many agents can work in parallel, each in its own git worktree so they do not overwrite files, automatic code review when an agent’s turn ends with findings that link to file and line, and checkpoints that let you undo a turn in one click. This lets you run one agent on server routes and another on a page component, then have a second model review both changes. See how it fits with parallel agent workflows in Best tools to run AI coding agents in parallel.

Final takeaways

opencode becomes a practical Nuxt assistant when you give it a short AGENTS.md, use small prompts, run the real test and build commands, and review SSR and Nitro-specific details yourself. Keep the agent inside Nuxt’s conventions and it will handle most route, composable, and test work cleanly. For larger changes, parallel sessions with worktrees and automatic review can keep multiple parts of the project moving without one agent breaking another’s work.