nuxt3-app
Skill2 starsChanged 35 days agoMITView on GitHub
Use when creating, structuring or debugging a Nuxt 3 or Nuxt 4 application — directory layout, server routes vs an external API, useFetch/useAsyncData, SSR-safe state with useState or Pinia, auth middleware, runtime config, hydration mismatches and choosing a deployment target. Enforces data fetching that runs once per request with stable keys and small payloads, state that never leaks between requests, and config that is read at runtime instead of baked at build.
- Reads credentials
In this repository13 other files it gives its agents.
- api-layer-axiosSkill
- element-plus-adminSkill
- pinia-stateSkill
- uni-app-cross-platformSkill
- vue2-to-vue3-migrationSkill
- vue3-compositionSkill
- vue-code-reviewSkill
- vue-forms-validationSkill
- vue-i18n-setupSkill
- vue-performanceSkill
- vue-router-authSkill
- vue-testing-vitestSkill
- wechat-miniprogramSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 67
Decide server routes vs external API: If the app owns the data or must hide an upstream secret, add server/api/<resource>.<method>.ts and …
- Very specific: line 106
Use status ('idle' | 'pending' | 'success' | 'error'), not the deprecated pending.
- Very specific: line 158
Call callOnce('cart', () => cart.load()) in app.vue or a layout for data that must load once per request and not again on the client.
- Distinctive: line 207
Test in a private window before blaming your code.
- Very specific: line 222
Cloudflare Workers/Pages: no Node built-ins (fs, native crypto streams, long timers), small bundle limits.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Nuxt 3 / Nuxt 4 applications
This skill applies to full Nuxt apps (SSR, hybrid or prerendered) built with
Vue 3, usually with Pinia and sometimes Element Plus or Nuxt UI. It covers
the decisions that differ from a plain Vite SPA: where code lives, what runs
on the server, how data reaches the client and how state survives
hydration. "Good" means the page renders once on the server, hydrates
without warnings, and the same build runs in dev, staging and production
with only environment variables changed. Skip it for ssr: false SPAs that
only use Nuxt as a file router; vue3-composition and vue-router-auth are
enough there. Component-level rules still come from vue3-composition.
Non-negotiables
- Know which major you are on before touching the tree. Nuxt 4 puts
app code in
app/(app/pages,app/components,app/app.vue) and keepsserver/,shared/,public/at the root; Nuxt 3 has everything at the root.~/@point atapp/in v4 and at the root in v3, so an import that works in one layout silently resolves elsewhere in the other. - Fetch in setup with
useFetch/useAsyncData; fetch in handlers with$fetch. The composables exist to run once on the server and hand the result to the client. Calling them inside a click handler or afterawaitof something else yields a double request or a "nuxt instance unavailable" error. - Every
useAsyncDatakey is unique per data shape. Two calls sharing a key share cache, state and the first handler that ran. Build keys from the resource and its params (`user-${id}`), never a bare'data'. - Only what the template needs goes into the payload. Everything the
fetch returns is serialised into the HTML (
__NUXT__). Usepickortransformto drop fields; a 2 MB product list in the payload doubles the page weight and the hydration time. - No module-level reactive state. A
refcreated at the top of a composable file or store module lives for the whole server process and is shared between users. Shared state goes throughuseState, a Pinia store (via@pinia/nuxt) ornuxtApp.payload. - Secrets live in
runtimeConfig, public values inruntimeConfig.public, and both get a default innuxt.config.ts. Only keys declared there can be overridden byNUXT_*environment variables at runtime. A key read fromprocess.envin a component is frozen at build time orundefinedon the client. - Auth state comes from a cookie, not
localStorage. The server render cannot readlocalStorage, so a token kept there produces a logged-out HTML followed by a logged-in flash and a hydration mismatch. UseuseCookieor an httpOnly session cookie read in a server route. - Route middleware decides access; server routes verify it again.
defineNuxtRouteMiddlewareruns on both server and client and can be bypassed by calling the API directly, so everyserver/apihandler that returns private data checks the session itself. import.meta.server/import.meta.clientguard browser APIs, withonMountedor<ClientOnly>for anything that renders differently in the browser.process.serveris deprecated andwindowat setup time crashes the server render.- Set
compatibilityDateand the Nitro preset explicitly once the deployment target is known. An auto-detected preset that changes between CI and local builds is the usual cause of "works locally, 500 in prod".
Workflow
- Read
nuxt.config.ts,package.jsonand the directory tree: Nuxt major and whetherfuture.compatibilityVersion: 4is set, SSR mode, modules (@pinia/nuxt,@nuxtjs/i18n,@nuxt/ui), existingruntimeConfigkeys,routeRules, and where auth currently lives. - Decide server routes vs external API. If the app owns the data or
must hide an upstream secret, add
server/api/<resource>.<method>.tsand call it with a relative URL. If a backend already exists, call it through$fetch.create({ baseURL: config.public.apiBase })in a plugin and useserver/apionly as a proxy for calls that need a secret. - Place the page under
pages/withdefinePageMetafor layout, middleware andkeepalive. Pick the fetch composable:useFetchfor a URL,useAsyncDatafor anything else (SDK call, two requests merged). Give it a key,default, andpick/transform. - Choose state scope: page-local
ref; cross-component but small →useState('cart'); domain with actions and several consumers → Pinia setup store. Initialise from the payload, never fromlocalStorage. - Add middleware (
middleware/auth.ts+definePageMeta({ middleware: 'auth' })orauth.global.ts) that returnsnavigateTo('/login', { redirectCode: 302 })with a validatedredirectquery. Add the matching session check inserver/utils/requireUser.tsand call it from private handlers. - Run
nuxi buildand start.output/server/index.mjslocally with the production env vars, open the page with JavaScript disabled once (does the server HTML look right?), then with it enabled and the console open (zero hydration warnings). Only then report done.
Patterns
useFetch with a stable key and a small payload
// wrong: key collides with every other 'list', whole response in payload, refetches on each query change twice
const { data } = await useAsyncData('list', () => $fetch('/api/orders', { query: query.value }))
// right
const { data: orders, status, refresh } = await useFetch('/api/orders', {
key: () => `orders-${JSON.stringify(query.value)}`,
query, // reactive: refetches when query changes
default: () => [] as OrderRow[], // Nuxt 4 data is undefined, not null, before first load
transform: (res: OrderListDto) => res.items.map(toRow), // only rows reach the payload
dedupe: 'cancel',
})Use status ('idle' | 'pending' | 'success' | 'error'), not the deprecated
pending. lazy: true (or useLazyFetch) when the page should render
before the data; then the template must handle status === 'pending'.
Forwarding cookies to your own API during SSR
// wrong: $fetch on the server sends no cookies, so /api/me sees an anonymous user
const me = await $fetch('/api/me')
// right: useFetch and useRequestFetch forward the incoming request headers
const { data: me } = await useFetch('/api/me')
const fetchWithCookies = useRequestFetch() // for calls outside useFetchServer route with validation and a session check
// server/api/orders/[id].get.ts
import { z } from 'zod'
const params = z.object({ id: z.string().regex(/^\d+$/) })
export default defineEventHandler(async (event) => {
const user = await requireUser(event) // server/utils, throws 401
const { id } = await getValidatedRouterParams(event, params.parse)
const order = await db.order.findFirst({ where: { id: Number(id), ownerId: user.id } })
if (!order) throw createError({ statusCode: 404, statusMessage: 'Order not found' })
return order
})server/middleware/*.ts runs on every request including assets; use it to
populate event.context (parse the session once), never to redirect pages
or return bodies.
useState vs Pinia vs module scope
// wrong: shared by every request on the server
const user = ref<User | null>(null)
export function useUser() { return user }
// right for a small shared value
export const useUser = () => useState<User | null>('user', () => null)
// right for a domain with actions: setup store, hydrated by @pinia/nuxt
export const useCartStore = defineStore('cart', () => {
const items = ref<CartItem[]>([])
async function load() { items.value = await useRequestFetch()('/api/cart') }
return { items, load }
})Call callOnce('cart', () => cart.load()) in app.vue or a layout for
data that must load once per request and not again on the client.
Auth middleware and runtime config
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
const session = useUserSession() // nuxt-auth-utils or your own cookie composable; works on server and client
if (session.loggedIn.value) return
const redirect = to.fullPath.startsWith('/') && !to.fullPath.startsWith('//') ? to.fullPath : '/'
return navigateTo({ path: '/login', query: { redirect } })
})// nuxt.config.ts
export default defineNuxtConfig({
compatibilityDate: '2026-10-01',
runtimeConfig: {
sessionSecret: '', // NUXT_SESSION_SECRET at runtime
public: { apiBase: '/api' }, // NUXT_PUBLIC_API_BASE
},
routeRules: { '/admin/**': { ssr: false }, '/docs/**': { prerender: true } },
})Private keys are undefined on the client by design; read them with
useRuntimeConfig(event) inside server routes.
Hydration mismatch checklist
Work through this list when the console shows "Hydration text/attribute
mismatch" or data-v-inspector points at nothing obvious:
- Time or randomness in render:
Date.now(),new Date().toLocale...,Math.random(),crypto.randomUUID(). Compute inonMountedor useuseId()for ids. - Locale or timezone formatting: server Node ICU and the browser disagree.
Format with an explicit
localeandtimeZone, or format on the client. - Browser-only branching:
isMobilefromnavigator,window.innerWidth,matchMedia. UseuseRequestHeaders(['user-agent'])on both sides or<ClientOnly>. - Storage-derived state: anything read from
localStorage/sessionStorageduring setup. Move to a cookie oronMounted. - Invalid HTML nesting the browser repairs:
<div>inside<p>,<a>inside<a>,<tr>outside<tbody>. The server emits it as written, the browser restructures it. - Third-party scripts or extensions mutating the DOM before hydration. Test in a private window before blaming your code.
- Component rendered under a different
v-ifon each side because the store was initialised on the client only. Hydrate it from the payload. - Mark the rare legitimate case (live clock) with
data-allow-mismatch(Vue 3.5+) instead of suppressing all warnings.
Deployment targets in one line each
- Node server (
node-server):node .output/server/index.mjs, honoursPORT/HOSTorNITRO_PORT. Default when nothing is detected. - Static (
nuxi generate): every route prerendered; dynamic routes neednitro.prerender.routesor crawling from links. No server routes at runtime, soserver/apionly works during generation. - Vercel / Netlify: presets auto-detected in their CI; ISR via
routeRules: { '/blog/**': { isr: 3600 } }. - Cloudflare Workers/Pages: no Node built-ins (
fs, nativecryptostreams, long timers), small bundle limits; test the preset locally withnuxi preview. - Docker: multi-stage, copy only
.output/, setNUXT_*env at run time, never bake a.envinto the image.
More detail on options and edge cases: references/data-fetching.md, references/deployment-targets.md.
Pitfalls
| Symptom | Cause | Fix |
| Request fires on server and again on client | $fetch in setup, or useFetch wrapped in a function called twice | Use useFetch/useAsyncData directly in setup |
| Two pages show each other's data | Same useAsyncData key | Key includes resource and params |
| HTML is 3 MB for a 50-row table | Full API response in the payload | pick/transform to rows only, paginate server-side |
/api/me returns anonymous during SSR, logged-in on client | $fetch without forwarded cookies | useFetch or useRequestFetch() |
| User A sees user B's name after deploy | Module-level ref or store singleton | useState or Pinia store created per request |
useRuntimeConfig().apiKey is undefined in a component | Private key read on the client | Move the call into a server route |
| Env var set in production is ignored | Key not declared in runtimeConfig or name not NUXT_* | Declare with a default; NUXT_PUBLIC_X for public |
.env works in dev, missing in prod | .env is loaded only by nuxi dev/build | Set real env vars in the process/container |
| "nuxt instance unavailable" | Composable called after an await or in a callback | Call composables synchronously at the top of setup |
| Hydration mismatch on dates | Server and browser locale differ | Explicit locale/timeZone, or format in onMounted |
| Logged-out flash before content | Token in localStorage | Cookie-based session |
| Middleware passes but API leaks data | Only the route middleware checks | requireUser(event) in every private handler |
~/components/X not found after v4 upgrade | Alias now points at app/ | Move files into app/ or use ~~/ for root |
data.value is undefined in a v-for | Nuxt 4 default changed from null | Provide default: () => [] |
Works with nuxi dev, 500 in Cloudflare | Node API used in a server route | Replace with Web APIs or switch preset |
| Prerendered page shows stale data forever | Static output with no revalidation | isr/swr route rule or a client refetch |
Before you finish
- Code sits in the right tree for the Nuxt major (
app/in v4) and aliases resolve as intended. - Every
useFetch/useAsyncDatahas a unique key, adefault, andpick/transformwhere the response is larger than the template needs. - No
$fetchor composable call in setup after anawait; handlers use$fetch; SSR calls that need cookies go throughuseFetch/useRequestFetch. - No reactive state at module scope; shared state uses
useStateor Pinia. runtimeConfigkeys declared with defaults; secrets are not inpublicand are never read in client code.- Private
server/apihandlers validate input and check the session. - Auth middleware validates its
redirecttarget; session comes from a cookie. - Production build started locally with real env vars; page renders with JS disabled and hydrates with zero warnings.
compatibilityDateand the Nitro preset match the actual target.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

