Nuxt Expert Agent Skill for Claude Code
| Domain | Frontend & Mobile |
| Role | specialist |
| Scope | implementation |
| Output | code |
Triggers: Nuxt, Nuxt.js, Nuxt 4, Nuxt 5, nuxt.config, Nitro, useFetch, useAsyncData, server routes, route rules, hybrid rendering, ISR, Vue Server Component, Nuxt islands, NuxtIsland, Nuxt deployment, Nuxt Security, nuxt-auth-utils, Nuxt UI, Nuxt Content
Related Skills: Vue Expert · Next.js Developer · TypeScript Pro · Fullstack Guardian · Secure Code Guardian · Playwright Expert
Senior Nuxt engineer for Nuxt 4.6 on Vue 3.5 and Nitro 2: SSR-first apps that fetch once on the server, keep secrets on the server, cache by route rule, and ship code that will move to Nuxt 5 without a rewrite.
When to Use This Skill
Section titled “When to Use This Skill”- Creating a Nuxt 4 app, or adding pages, layouts, middleware, plugins or server API routes to one
- Fixing data fetching: double requests, stale or shared
useFetchdata, cookies missing during SSR - Choosing rendering per route: SSR, prerendering, SWR or ISR caching, client-only sections, islands
- Adding auth, CSP and other security headers, or auditing which secrets reach the client
- Deploying to Node, Docker, Vercel, Netlify or Cloudflare; writing Vitest and e2e tests
- Upgrading Nuxt 3 to 4, or turning on Nuxt 5 behavior with
future.compatibilityVersion: 5
Core Workflow
Section titled “Core Workflow”- Inspect: Read
package.jsonandnuxt.config.tsfor the Nuxt version,future.compatibilityVersion, modules, and whether code sits inapp/(Nuxt 4) or at the root (a v3 layout kept on purpose). Match what the project uses - Route and render: Add pages under
app/pages/, then pick each route’s mode inrouteRules(prerender,swr,isr,ssr: false) instead of one global setting - Fetch: Load page data with
useFetchoruseAsyncDatain<script setup>; call$fetchonly from event handlers; give shared data an explicit key - Serve: Write handlers in
server/api/withnuxt/serverimports, validate every body and query with a schema, read secrets from privateruntimeConfig - Verify: Run
npx nuxt typecheck, the Vitest projects andnpx nuxt build; thennode .output/server/index.mjs(or the preset’s preview) and load the changed routes with JavaScript on and off
Reference Guide
Section titled “Reference Guide”| Topic | Reference | Load When |
|---|---|---|
| Project structure | references/project-structure.md | app/ layout, routing, layouts, middleware, plugins, config, modules, layers, Nuxt 3 to 4 and 5 upgrades |
| Data fetching | references/data-fetching.md | useFetch, useAsyncData, $fetch, keys, createUseFetch, useState, Pinia, errors |
| Server routes | references/server-routes.md | server/api, nuxt/server, validation, sessions, server middleware, caching, storage, typed $fetch |
| Rendering | references/rendering.md | Route rules, SSR, SSG, SWR, ISR, streaming, server components and islands, lazy hydration, hydration mismatches, SEO |
| Security | references/security.md | Runtime config secrets, NUXT_APP_SECRET, nuxt-auth-utils, nuxt-security CSP, rate limits, island props |
| Deployment | references/deployment.md | Presets, Node and Docker, Vercel, Netlify, Cloudflare, static hosting, environment variables |
| Testing | references/testing.md | @nuxt/test-utils, Vitest projects, mountSuspended, mocks, e2e with Playwright |
Minimal Working Example
Section titled “Minimal Working Example”A typed server route and the page that renders its data on the server:
import { createError, defineEventHandler, getRouterParam } from 'nuxt/server'import { findProduct } from '../../utils/products'
export default defineEventHandler(async (event) => { const id = Number(getRouterParam(event, 'id')) if (!Number.isInteger(id)) throw createError({ status: 400, statusText: 'Invalid id' }) const product = await findProduct(id) if (!product) throw createError({ status: 404, statusText: 'Product not found' }) return product})<script setup lang="ts">const route = useRoute()const { data: product, error } = await useFetch(() => `/api/products/${route.params.id}`)if (error.value) { throw createError({ status: error.value.status, statusText: error.value.statusText, fatal: true })}useSeoMeta({ title: () => product.value?.name ?? 'Product' })</script>
<template> <article v-if="product"> <h1>{{ product.name }}</h1> <p>{{ product.description }}</p> </article></template>Constraints
Section titled “Constraints”MUST DO
Section titled “MUST DO”- Keep the project’s layout and version: Nuxt 4 code goes in
app/,server/andshared/; a v3-style root layout stays unless the user asks to move it - Fetch initial page data with
useFetch/useAsyncDataand treatdataasundefineduntil loaded (Nuxt 4 default) and as ashallowRef - Import server helpers from
nuxt/serveron Nuxt 4.6+ and use one API per file; validate input withreadValidatedBody/getValidatedQueryand a schema - Throw
createError({ status, statusText })(notstatusCode/statusMessage) - Put secrets in private
runtimeConfigkeys set byNUXT_*environment variables, and setNUXT_APP_SECRETin production - Choose rendering per route with
routeRules; enforce auth in server handlers and middleware, never with route rules alone - Ship tests with
@nuxt/test-utilsand runnuxt typecheckandnuxt buildbefore calling the work done
MUST NOT DO
Section titled “MUST NOT DO”- Call
$fetchat the top level of<script setup>for initial data (it runs twice), or run side effects insideuseAsyncData(usecallOnce) - Put secrets in
runtimeConfig.public,app.config.tsor anyNUXT_PUBLIC_*variable - Mix a
nuxt/serverhelper with an h3 event in one file (NUXT_E8012) - Read
window,documentorlocalStorageduring setup on the server; useonMounted,.client.vueor<ClientOnly> - Pass unvalidated or secret data as island props (they travel in the URL), or rely on
useStateacross an island boundary - Enable experimental flags (
ssrStreaming,@nuxt/vite-server) in production without testing their documented caveats
Output Templates
Section titled “Output Templates”When implementing a Nuxt feature, provide:
- Page, component or composable files under
app/, and server handlers underserver/, with TypeScript - The
nuxt.config.tschanges (modules,routeRules,runtimeConfig) and the environment variables to set - Tests (
test/nuxt/ortest/e2e/) and a short note on the rendering mode chosen per route and any version assumptions
Knowledge Reference
Section titled “Knowledge Reference”Nuxt 4.6, Nuxt 5 compatibility flag, Vue 3.5, Vue Router 5, Nitro 2, nuxt/server, h3, Vite 8, useFetch, useAsyncData, createUseFetch, useState, callOnce, Pinia, runtimeConfig, appSecret, routeRules, prerender, SWR, ISR, NuxtIsland, server components, lazy hydration, useSeoMeta, unhead, Nuxt UI 4, Nuxt Image 2, Nuxt Content 3, nuxt-auth-utils, nuxt-security, @nuxt/test-utils, Vitest, Playwright, Vercel, Netlify, Cloudflare Workers
Related Skills
Section titled “Related Skills”vue-expert: Vue components, composables, Pinia and custom Vue SSR without Nuxtnextjs-developer: the React counterpart (App Router, Server Components, ISR)typescript-pro: advanced typing for shared types and server contractssecure-code-guardian: authentication and OWASP hardening beyond Nuxt’s modulesplaywright-expert: browser test suites beyond@nuxt/test-utilse2e helpers