onmax Nuxt Skill Index
This file keeps the highest-frequency Nuxt decisions in context. Use it to avoid generic Vue fallbacks, then route into the right Nuxt pack, Vue guidance, or module delta skill.
Monorepo Scope
This skill applies only to the playground subtree of this monorepo.
Treat files and tasks outside playground as out of scope unless the user explicitly redirects you there.
Activation Flow
- Explore the project first: inspect the real page, component, route, server handler, collection, or module surface you are changing.
- Use the routing sections in this file and load the smallest matching Nuxt pack.
- If the remaining work is mainly Vue component, composable, reactivity, or SFC work, open Vue Best Practices.
- If module authoring is part of the task, load Module Authoring Conventions before changing
defineNuxtModule, runtime extensions, hooks, or release scaffolding. - If an installed module owns the problem, open its entry under references/modules.
- Apply module guidance as delta-only rules inside that module's APIs, config, runtime behavior, and owned files.
High-Frequency Nuxt Decisions
- If the task touches SSR, initial page load, or route-driven data, prefer
useFetchoruseAsyncDatabeforeonMountedplus$fetch. - If the task changes page options, layout selection, route middleware, or page-level behavior, check
definePageMetabefore adding ad hoc wiring. - If the task changes title, meta tags, canonical URLs, or OG data, check
useHeadoruseSeoMetabefore page-meta or template markup. - If content lives in JSON or YAML records, or the UI needs generated docs navigation, choose data collections and collection-navigation primitives before manual assembly.
- If the UI surface is page chrome, a table, a form, a modal, a command palette, or a dropdown, prefer a Nuxt UI primitive before raw HTML or custom listeners.
- If runtime config, tokens, secrets, or privileged API calls are involved, keep them server-side and expose only a server route or the minimum public config.
- If hydration, browser-only APIs, time, randomness, or cookies are involved, use SSR-safe primitives first and isolate browser-only work behind
ClientOnlyoronMounted. - If the fix touches errors, fallback UI, or recovery flow, check both global and local surfaces before concluding the work is complete.
- If the solution looks correct but uses generic Vue or hand-rolled HTML, confirm Nuxt, Nuxt Content, or Nuxt UI does not already own that abstraction.
- If the task is module-specific, use the module entry and keep module guidance scoped; do not replace broad Nuxt rules with module-specific rules.
Precedence
- Repository-global instructions and required workflows win first.
- This file keeps the common Nuxt forks in context.
- Nuxt packs provide deeper framework guidance.
- Vue guidance covers component, composable, and SFC patterns after the Nuxt decision is settled.
- Module entries add delta-only guidance inside explicit module scope.
How to use this skill map
Explore the current surface first: page, layout, component, server handler, content collection, or module-owned file.
Load the first matching Nuxt pack from the routing table below.
If the remaining work is mainly Vue component or composable implementation, switch to Vue Best Practices.
Open deeper Nuxt packs only when the first pack points you there.
If an installed module is involved, open its entry under
references/modules.Copied skills go straight to their
SKILL.md; metadata-routed modules only expose docs and source links.
Common forks in the road
| Task shape or symptom | Load first | Why |
|---|---|---|
| SSR, initial page load, route params, or hydration-sensitive data | Data Fetching and SSR | Prefer useFetch or useAsyncData over setup-time $fetch or onMounted fetches. |
| Page options, route middleware, layout selection, title, meta tags, or OG data | Page Meta, Head, and Layout | Separate page behavior from document metadata and layout structure before editing. |
| A generic Vue fix or raw HTML implementation looks tempting | Abstraction Disambiguation | Check whether Nuxt, Nuxt Content, or Nuxt UI already owns the abstraction. |
The remaining work is mostly .vue components, composables, reactivity, or SFC structure |
Vue Best Practices | Switch to Vue-specific guidance after the Nuxt ownership and routing decisions are already settled. |
Global errors, local fallback UI, clearError, showError, or recovery flows |
Error Surfaces and Recovery | Nuxt error handling often needs both global and local surfaces to be correct. |
| Secrets, runtime config, privileged API calls, or server/client boundary confusion | Architecture Boundaries | Move sensitive logic server-side first, then pair with config and route rules as needed. |
| Before finishing a fix that spans multiple files or surfaces | Verification and Finish | Re-check paired surfaces and verify framework behavior, not only the visible output. |
Vue guidance
Use Vue Best Practices when the task is mainly Vue component, composable, reactivity, props/emits, or SFC work and Nuxt no longer owns the abstraction.
Start with these must-read Vue references:
All Nuxt packs
| Pack | Focus | Typical triggers |
|---|---|---|
| Abstraction Disambiguation | Choose Nuxt-owned abstractions before generic Vue, raw HTML, or ad hoc glue code. | A generic Vue or HTML fix looks plausibleYou need to decide whether Nuxt, Nuxt Content, or Nuxt UI already owns the surface |
| Page Meta, Head, and Layout | Separate page behavior, document metadata, and layout structure before editing. | Pages, layouts, middleware, or page optionsTitle, meta tags, canonical URLs, or OG metadata |
| Error Surfaces and Recovery | Cover both global and local error boundaries and use the right recovery utilities. | Global error pages or local error boundariesRecovery flows, clearError, showError, or fallback UI |
| Verification and Finish | Verify the intended framework behavior and re-check paired surfaces before concluding work. | The fix spans more than one surfaceYou are about to finish a Nuxt change and need to confirm the right abstraction |
| Data Fetching and SSR | Deduplication, payload correctness, and request-safe loading. | Pages, layouts, or composables fetching initial dataSSR-visible content or hydration-sensitive state |
| Hydration and SSR Consistency | SSR/CSR determinism, client-only boundaries, and mismatch prevention. | Hydration warnings or client-only renderingState that differs between server and browser |
| Architecture Boundaries | Server-only secrets, request isolation, and safe shared abstractions. | Crossing server/client boundariesComposable or utility architecture changes |
| Server Routes and Runtime Config | Runtime config exposure, env handling, and route-level contracts. | nuxt.config, runtime config, or env wiringServer route config and public/private config exposure |
| Nitro and h3 Server Patterns | Handler contracts, caching, and edge-safe server behavior. | Server routes, middleware, Nitro plugins, or h3 handlersAPI behavior, caching, or edge runtime concerns |
| Plugins and Runtime Boot | Plugin ordering, startup cost, and app/runtime initialization. | Plugins, app boot logic, or injected runtime helpersGlobal runtime behavior changes |
| Performance and Rendering | Rendering strategy, payload cost, and lazy loading tradeoffs. | Performance regressions or rendering strategy changesLink, asset, and bundle cost decisions |
| Module Authoring Conventions | Nuxt Kit patterns, module lifecycle, and ecosystem-safe authoring. | Writing or refactoring a Nuxt moduleModule install/setup conventions |
| Migrations and Compatibility | Incremental upgrades, compatibility boundaries, and rollout safety. | Upgrades, deprecations, or breaking behavior changesCompatibility fixes across Nuxt versions |
Module guides
Open the linked module entry first. Copied skills link straight to their SKILL.md; metadata-routed modules use a small docs/source router when no copied skill exists.
Resolved module skills
- @nuxt/ui
v4.5.1- Resolved module skill. Trust:official. Build UIs with @nuxt/ui v4 — 125+ accessible Vue components with Tailwind CSS theming. Use when creating interfaces, customizing themes to match a brand, building forms, or composing layouts like dashboards, docs sites, and chat interfaces.
Metadata-routed skills
- @nuxthub/core
v0.10.5- Metadata-routed skill. Trust:official. Build full-stack Nuxt applications, with zero configuration. - @onmax/nuxt-better-auth
v0.0.2-alpha.30- Metadata-routed skill. Trust:official. Nuxt module for Better Auth integration with NuxtHub, route protection, session management, and role-based access
Skipped or unavailable
- @onmax/nuxt-better-auth /
nuxt-better-auth(dist): SKILL.md is required at skill root. Use the relevant Nuxt pack plus the module's official docs.
Before Completion
- Did I choose a Nuxt primitive where a generic Vue or raw HTML solution would be tempting?
- Did I check whether the fix needs a second surface such as global or local, or server or client?
- Did I choose the right concept pair: page meta vs head, data collection vs page collection, component primitive vs custom markup?
- Did I verify the framework behavior that matters, not just the visible output?
Primary Packs
Start with Abstraction Disambiguation, Page Meta, Head, and Layout, Error Surfaces and Recovery, Verification and Finish, Data Fetching and SSR when the task matches one of those common routes.
Generated by nuxt-skill-hub. Do not edit this file manually.