Home › Vue / Nuxt › Nuxt 4 AGENTS.md

Nuxt 4 AGENTS.md

AGENTS.md for Nuxt 4 apps: the app/ directory layout, data fetching keys, server routes with validation, and runtime config.

AGENTS.mdVue / Nuxt

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Nuxt 4

## Commands
`npm run dev` · `npm run build` · `npx nuxi typecheck` · `npm run lint` · `npx vitest run` (with `@nuxt/test-utils`)

## Layout (Nuxt 4)
- App code in `app/` (`app/pages`, `app/components`, `app/composables`, `app/layouts`, `app/middleware`). Server code in `server/` (`server/api`, `server/routes`, `server/utils`). Shared types/utils in `shared/`.
- Auto-imports are on; don't add manual imports for Vue/Nuxt composables or components in those folders.

## Data
- Fetch with `useFetch('/api/orders')` or `useAsyncData('orders', () => $fetch(...))` with a stable key; don't call `$fetch` directly in `setup` for SSR data (it double-fetches).
- Handle `pending`/`status` and `error` in templates. Use `watch` options or reactive params for refetching.
- Shared SSR-safe state via `useState('key', () => init)`, Pinia for larger stores.

## Server routes
- `server/api/orders.post.ts` with `defineEventHandler`. Validate with `readValidatedBody(event, schema.parse)` / `getValidatedQuery` (zod). Throw `createError({ statusCode: 400, statusMessage })`.
- Auth checked in each handler via a `server/utils` helper (`requireUser(event)`).

## Config
- `runtimeConfig` in `nuxt.config.ts` for secrets (server only) and `runtimeConfig.public` for client-safe values; override with `NUXT_*` env vars. Never read `process.env` in app code.

## Done
Typecheck, lint, tests, and `npm run build` pass.