ub-nuxt

name: ub-nuxt description: Use this skill for Nuxt framework, runtime, and app-structure work. Apply it when the task involves nuxt.config.*, Nuxt modules, middleware or plugins, runtime config, Nitro or server routes, rendering or deployment mode, data fetching, route structure, app setup, or Nuxt migration.

UB Nuxt

Overview

Use this skill to keep Nuxt work current-version aligned, type-safe, and framework-native. This skill targets the latest stable Nuxt: enforce the app/-first source layout, modern Nuxt runtime defaults, and current Vue + TypeScript patterns while rejecting legacy directory guidance.

Implement against the detected project and runtime truth, but bias framework guidance toward forward-compatible migration rather than preserving legacy layouts, outdated recipes, or compatibility-layer drift by default.

Load References On Demand

• Read ../ub-authoring/references/authoring-conventions.md when adjusting routing guidance or cross-skill authoring conventions.
• Read references/nuxt-vue-patterns.md for architecture, data-fetching, routing, server, and rendering guidance.
• Read references/typescript-modern.md for strict TypeScript defaults, typing patterns, and anti-pattern checks.
• Read references/ecosystem-preferences.md for modern package preferences, VueUse-first heuristics, and replacement matrix.
• Read references/nuxt-legacy-to-modern-migration.md for migration deltas, codemod mapping, and compatibility caveats.

When Not To Use

• Do not use this skill when the task is framework-agnostic Vue component or composable logic without Nuxt runtime, app-directory, or Nitro concerns; co-load or defer that to ub-vuejs depending on whether Vue authoring remains a first-class concern.
• Do not use this skill when the primary change surface is pure CSS or Tailwind integration rather than Nuxt framework behavior; co-load the relevant styling skill when the task spans both surfaces.

Core Workflow

1. Detect Nuxt generation and active toolchain from package.json, nuxt.config.*, lockfiles, and modules. Always inspect srcDir, future.compatibilityVersion, and app/ directory presence.
2. Decide rendering/runtime mode first (SSR, SSG, hybrid, edge/server) before writing code.
3. Compare official guidance, repo truth, and observed code reality for non-trivial or version-sensitive recommendations.
4. Surface OFFICIAL_CONFLICT when authoritative sources, repo truth, or live code reality materially disagree on a non-trivial recommendation.
5. Surface UNVERIFIED when a non-trivial claim could not be confirmed in official sources after targeted research.
6. Implement features with Composition API, <script setup lang="ts">, typed composables, and server/client separation.
7. Prefer VueUse and modern ecosystem defaults from references/ecosystem-preferences.md.
8. Apply modern Nuxt runtime semantics from references/nuxt-vue-patterns.md and migration deltas from references/nuxt-legacy-to-modern-migration.md.
9. Reject legacy Nuxt/Vue patterns and replace them with current equivalents.
10. Validate types, lint/build output, and framework-specific constraints after edits.

Nuxt Modern Structure Contract (Hard Requirement)

• Place all app source in app/:
  • app/pages, app/components, app/layouts, app/middleware, app/plugins
  • app/app.vue, app/app.config.ts
• Keep runtime and project roots at repository root:
  • server/, shared/, public/, modules/, nuxt.config.ts
• Respect srcDir if explicitly configured, but still apply modern Nuxt structure semantics within that source root.
• Treat future.compatibilityVersion as a required detection signal:
  • if present and below the current stable version, call out mismatch and provide correction guidance.
• Do not scaffold or recommend legacy root app directories:
  • pages/, components/, layouts/, middleware/, plugins/ at repository root.

Implementation Rules

Nuxt and Vue

• Use Nuxt-native primitives (useAsyncData, useFetch, Nitro server routes, plugins, runtime config) instead of custom framework bypasses.
• Use Composition API and composables for reuse; avoid Options API for new work unless explicitly required.
• Keep data ownership clear across server routes, server composables, and client composables.
• Prefer auto-imported Nuxt utilities and composables where they improve consistency.
• Enforce modern Nuxt directory and runtime defaults when generating or reviewing code; do not emit legacy directory placements.

TypeScript

• Enable strict TypeScript behavior and avoid any in application code.
• Type runtime config, API responses, composable contracts, and emits/props explicitly.
• Prefer inferred types where stable; add explicit exported/public types at boundaries.
• Use modern TypeScript features that improve correctness (satisfies, const assertions, template literal types, discriminated unions).

Ecosystem and Package Selection

• Prefer VueUse before introducing utility packages for reactivity, browser APIs, sensors, lifecycle wrappers, and async helpers.
• Choose Nuxt ecosystem modules and actively maintained libraries with strong TypeScript support.
• Keep dependencies minimal; remove redundant packages when Nuxt/VueUse/standard platform APIs already solve the need.
• Defer deep Tailwind guidance to .agents/skills/ub-tailwind/SKILL.md; keep only integration-level Tailwind notes in Nuxt tasks.

Legacy-Avoidance Guardrails

• Do not scaffold or recommend legacy Nuxt directory conventions that conflict with modern Nuxt defaults.
• Do not introduce Vue 2-era patterns (mixins, filters, class-style component decorators) for new implementation.
• Do not default to ad-hoc global stores or plugin side effects when composables or typed stores are clearer.
• Do not use old router/data-fetching idioms when Nuxt-native patterns are available.
• Do not generate app source files in root-level pages/, components/, layouts/, middleware/, or plugins/.

Version & Research Policy

• Target the latest stable release of Nuxt.
• Detect the project's actual Nuxt version from package.json, nuxt.config.*, and lockfiles.
• Use web search to verify current best practices, API availability, and migration guidance against official Nuxt documentation.
• Treat repo truth as the gold implementation standard when deciding what can actually ship safely in the current project.
• Treat official Nuxt docs as the preferred guidance baseline for forward-looking design and migration-ready patterns.
• If official guidance and repo truth diverge materially on a non-trivial recommendation, surface OFFICIAL_CONFLICT, implement the repo-safe path, and explain the migration path.
• If official sources disagree with each other on a non-trivial recommendation, also surface OFFICIAL_CONFLICT instead of silently collapsing the disagreement.
• If a non-trivial claim cannot be confirmed in official sources after targeted research, mark it UNVERIFIED or avoid presenting it as settled guidance.
• Keep conflict and uncertainty disclosure scoped to non-trivial, version-sensitive, or contested guidance rather than trivial edits.
• When the project's installed version is behind latest stable, note the version gap and recommend an upgrade path.
• Inspect the host repository's AGENTS.md or equivalent instructions when present for project-specific version policy and tooling; do not assume it contains this catalog's defaults.
• Do not hardcode version numbers in generated guidance — keep recommendations evergreen.

Freshness Review

• Volatility: high
• Review recommendation: review on touch and during periodic maintenance, targeting a quarterly rhythm when practical.
• Trigger signals: Nuxt release-cycle changes, updated framework migration guides, runtime defaults shifts, or ecosystem-module guidance changes.
• Enforcement: advisory only; freshness markers should prioritize review, not block unrelated Nuxt work automatically.
• Stable core: Nuxt-native primitives, clear server/client boundaries, and app-source versus runtime-root separation remain the stable principles even when recipes evolve.

Output Requirements

When generating or reviewing code, always include:

1. A short environment detection note (Nuxt generation, Vue version family, TS strictness state).
2. A source truth note: detected project version, runtime layout, and any material gap versus latest stable guidance.
3. A modern Nuxt structure compliance note (app/ placement, root runtime dirs, srcDir handling, future.compatibilityVersion status).
4. The selected rendering/runtime strategy and why it fits.
5. The package selection rationale when adding dependencies (especially VueUse vs alternatives).
6. A concise list of legacy patterns removed or avoided.
7. Validation actions performed (typecheck/build/test/lint as available).
8. Conflict note when relevant: OFFICIAL_CONFLICT or UNVERIFIED with a concise explanation and the implementation consequence.

Completion Checklist

• Nuxt mode and toolchain are identified before edits.
• Modern Nuxt structure contract is satisfied (app/ app source; root runtime dirs).
• Composition-first and Nuxt-native patterns are used throughout.
• TypeScript boundary types are explicit and any is avoided.
• VueUse-first preference is applied for utility/reactive helpers.
• Added dependencies are modern, maintained, and justified.
• Tailwind details are delegated to ub-tailwind when needed.
• Legacy patterns are replaced, not carried forward.
• Any material official-source conflict or unverified non-trivial guidance is disclosed explicitly when relevant.