Skip to content

Nuxt + AI SDK + Tailwind rules for AI coding agents

Full stack: Nuxt (Vue 3) + Tailwind CSS v4 + Vercel AI SDK + Zod validation

Ready-to-commit rules for Nuxt (Vue 3) + Tailwind CSS v4 + Vercel AI SDK + Zod validation in every major format: AGENTS.md (Codex, Cursor, Copilot), CLAUDE.md (Claude Code), Cursor .mdc project rules, legacy .cursorrules, Copilot instructions, Windsurf rules and GEMINI.md. An AI chat app or agent UI built with Nuxt, Vue 3 and the Vercel AI SDK, streaming replies from Nuxt server routes.

Last reviewed 2026-11-11 · Customise in the generator · Raw: AGENTS.md, CLAUDE.md

The mistake agents make most on this stack

Agents call the model from a Vue component or put the provider API key in `runtimeConfig.public`, which ships it to the browser, instead of keeping model calls in a `server/api/` route.

Generated files

AGENTS.md
# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Nuxt (Vue 3) + Tailwind CSS v4 + Vercel AI SDK + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Vercel AI SDK, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## Project structure

- Pages in `pages/`, components in `components/`, composables in `composables/`, API routes in `server/api/`.
- Nuxt 4 moves app code under `app/`; follow the layout the project already uses.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Vercel AI SDK

- Check the installed `ai` package major version; tool and message APIs changed between majors.
- Call models only from server code (route handlers or Server Actions). API keys never reach the browser.
- Stream long responses with `streamText`; use `generateObject`/structured output with a Zod schema when you need JSON.
- Define tools with `tool()` and a Zod input schema; validate and authorize inside each tool before acting.
- Keep model IDs in one config module so they can be swapped without hunting through the code.
- Set `maxOutputTokens`/step limits and handle errors and aborts in the UI.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Reference docs

- [Nuxt docs](https://nuxt.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [AI SDK docs](https://ai-sdk.dev/docs)
- [Zod docs](https://zod.dev)

Commands your agent should run

TaskCommand
Dev servernpm run dev
Buildnpm run build
Type checknpx nuxi typecheck

What the rules cover

Nuxt (Vue 3)

Nuxt full-stack Vue 3 app with TypeScript. Scoped to **/*.vue, server/**/*.ts, composables/**/*.ts, app/**/*.ts in Cursor, Copilot and Windsurf.

  • Use <script setup lang="ts"> and the Composition API.
  • Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
  • Fetch data with useFetch or useAsyncData so it works with SSR. Avoid raw fetch inside onMounted for page data.
  • Server routes go in server/api/ using defineEventHandler; validate bodies with readValidatedBody.
  • Secrets go in runtimeConfig (server-only keys) and env vars. Only runtimeConfig.public reaches the browser.
  • Use useState for SSR-safe shared state or Pinia for larger stores.

Source docs: Nuxt docs

Tailwind CSS v4

Utility-first styling with Tailwind CSS v4. Scoped to **/*.css, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.blade.php, **/*.erb in Cursor, Copilot and Windsurf.

  • Tailwind v4 is configured in CSS: @import "tailwindcss"; plus @theme { ... } for design tokens. Do not create a tailwind.config.js unless the project already has one.
  • Use theme tokens (colors, spacing) instead of arbitrary values like w-[37px].
  • Build responsive layouts mobile-first with sm:, md:, lg: prefixes.
  • Extract repeated class lists into components, not @apply chains.
  • Support dark mode with the dark: variant when the project uses it.

Source docs: Tailwind CSS docs

Vercel AI SDK

LLM features with the Vercel AI SDK. Scoped to **/ai/**/*.ts, app/api/**/*.ts, **/*chat*.tsx in Cursor, Copilot and Windsurf.

  • Check the installed ai package major version; tool and message APIs changed between majors.
  • Call models only from server code (route handlers or Server Actions). API keys never reach the browser.
  • Stream long responses with streamText; use generateObject/structured output with a Zod schema when you need JSON.
  • Define tools with tool() and a Zod input schema; validate and authorize inside each tool before acting.
  • Keep model IDs in one config module so they can be swapped without hunting through the code.
  • Set maxOutputTokens/step limits and handle errors and aborts in the UI.

Source docs: AI SDK docs

Zod validation

Runtime schema validation with Zod. Scoped to **/*.ts, **/*.tsx in Cursor, Copilot and Windsurf.

  • Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
  • Derive TypeScript types from schemas with z.infer<typeof schema>; do not hand-write duplicate types.
  • Use safeParse where you need to return validation errors to the user.

Source docs: Zod docs

How to install

  1. Copy AGENTS.md to your repo root. That covers Codex, Cursor, GitHub Copilot and most other agents.
  2. Using Claude Code? Add a CLAUDE.md with the single line @AGENTS.md, or use the standalone CLAUDE.md tab above.
  3. Want rules that only load for certain files in Cursor? Add the .cursor/rules/*.mdc files.
  4. Commit the files so your whole team (and every agent) shares them.

Format guides: AGENTS.md · CLAUDE.md · Cursor rules (.mdc) · .cursorrules (legacy) · Copilot instructions · Windsurf rules · GEMINI.md

FAQ

Where do I put the AGENTS.md for Nuxt (Vue 3) + Tailwind CSS v4 + Vercel AI SDK + Zod validation?

Save it as AGENTS.md in the root of your repository, next to your main config file. Codex, Cursor and GitHub Copilot pick it up automatically. For Claude Code, add a CLAUDE.md containing @AGENTS.md (or use the standalone CLAUDE.md on this page).

What is the most common mistake AI agents make with Nuxt (Vue 3)?

Agents call the model from a Vue component or put the provider API key in runtimeConfig.public, which ships it to the browser, instead of keeping model calls in a server/api/ route.

Which commands should the agent run to check its work?

For this stack: npm run dev, npm run build, npx nuxi typecheck. They are listed in the generated files so the agent runs them before finishing a task.

Do these Nuxt (Vue 3) + Tailwind CSS v4 + Vercel AI SDK + Zod validation rules work with Cursor and Claude Code?

Yes. This page includes the same rules as AGENTS.md, CLAUDE.md, Cursor .mdc project rules, a legacy .cursorrules file, GitHub Copilot instructions, Windsurf rules and GEMINI.md.

Can I customise these rules?

Yes. Open this stack in the generator to add or remove libraries, set your project name and package manager, switch beginner explanations on, and download everything as a zip.

Related stacks