nuxt-skill-hub 0.0.1-beta.1

package/nuxt-best-practices/rules/nitro-h3-patterns.md

@@ -0,0 +1,96 @@
+## Nitro and h3 Server Patterns
+
+### Rule ID: `nitro-validated-input-helpers`
+### Rule: Use h3 validated helpers for route params, query, and body
+### When to apply
+Creating or refactoring `server/api/*` handlers with external input.
+
+### Wrong pattern
+Casting `event.context.params`, `getQuery(event)`, or `readBody(event)` to trusted shapes without validation.
+
+### Recommended pattern
+Use `getValidatedRouterParams`, `getValidatedQuery`, and `readValidatedBody` (for example with Zod parsers) at handler boundaries.
+
+### Nuxt-specific caveat
+Nuxt server routes run on h3; validated helpers provide both runtime safety and stronger type flow than ad-hoc casting.
+
+### Execution checklist
+- [ ] Inputs to inspect: all untrusted handler inputs (params/query/body).
+- [ ] Minimal verification: invalid inputs return explicit client-safe errors.
+- [ ] Stop condition: accepted schema/validator is not available in project constraints.
+
+### Rule ID: `nitro-waituntil-for-nonblocking-work`
+### Rule: Move non-critical async side work to `event.waitUntil`
+### When to apply
+Logging, cache warmup, or analytics in server handlers that should not delay response.
+
+### Wrong pattern
+Awaiting non-essential async jobs before sending response.
+
+### Recommended pattern
+Return response early and schedule non-critical work with `event.waitUntil(...)`.
+
+### Nuxt-specific caveat
+`event.waitUntil` integrates with runtime providers to finish background work after response, including edge-like runtimes.
+
+### Execution checklist
+- [ ] Inputs to inspect: awaited tasks in request critical path.
+- [ ] Minimal verification: response path no longer blocks on non-critical work.
+- [ ] Stop condition: task result is required to compute response.
+
+### Rule ID: `nitro-cache-varies-for-tenant-host`
+### Rule: Configure `cache.varies` when caching depends on request headers
+### When to apply
+Using Nitro cache/route rules with host-aware or tenant-aware logic.
+
+### Wrong pattern
+Reading host-based request data under cached routes without declaring varying headers.
+
+### Recommended pattern
+Set `cache.varies` for headers that affect output (typically `host`, `x-forwarded-host` in multi-tenant setups).
+
+### Nuxt-specific caveat
+With cached responses, incoming request headers are dropped by default; `useRequestURL()` can otherwise resolve host as `localhost`.
+
+### Execution checklist
+- [ ] Inputs to inspect: cached route logic that branches on headers/host.
+- [ ] Minimal verification: cache keys vary by intended tenant headers.
+- [ ] Stop condition: output is fully header-invariant.
+
+### Rule ID: `nitro-api-error-shape-client-safe`
+### Rule: Use client-safe API error shape in server handlers
+### When to apply
+Throwing errors from `server/api/*` endpoints consumed by clients.
+
+### Wrong pattern
+Throwing generic errors or relying on long/internal `message` values to reach clients.
+
+### Recommended pattern
+Throw `createError` with explicit `status` and short `statusText`; use `data` for structured client payload and keep sensitive detail server-side.
+
+### Nuxt-specific caveat
+In API routes, `statusText` is the safer client-facing channel; avoid embedding dynamic user input in messages.
+
+### Execution checklist
+- [ ] Inputs to inspect: thrown API errors and exposed message payloads.
+- [ ] Minimal verification: consistent status code/text contract with no sensitive leakage.
+- [ ] Stop condition: upstream error contract cannot be mapped safely.
+
+### Rule ID: `nitro-runtime-config-from-event`
+### Rule: Prefer `useRuntimeConfig(event)` in server routes
+### When to apply
+Accessing runtime config inside server handlers.
+
+### Wrong pattern
+Reading config without event context in handlers that may depend on runtime overrides.
+
+### Recommended pattern
+Pass `event` to `useRuntimeConfig(event)` in server handlers.
+
+### Nuxt-specific caveat
+Passing event is optional but recommended for runtime-overridden environment values in route execution.
+
+### Execution checklist
+- [ ] Inputs to inspect: server handlers using runtime config.
+- [ ] Minimal verification: handler config values resolve correctly in runtime deployment environment.
+- [ ] Stop condition: execution context is not an h3 event handler.

package/nuxt-best-practices/rules/nuxt-ui-primitives.md

@@ -0,0 +1,58 @@
+## Nuxt UI Primitives
+
+### Rule ID: `ui-primitives-before-custom-markup`
+### Rule: Prefer Nuxt UI primitives before custom markup
+### When to apply
+Building or fixing page chrome, tables, forms, modals, command palettes, dropdowns, or similar UI surfaces.
+
+### Wrong pattern
+Rebuilding a UI surface with raw HTML, custom keyboard handlers, or ad hoc styling when Nuxt UI already provides a first-class component.
+
+### Recommended pattern
+Start with the Nuxt UI primitive first and only fall back to custom markup when the primitive cannot express the required behavior.
+
+### Nuxt-specific caveat
+Nuxt UI tasks often fail because agents build something that looks correct while bypassing the intended component.
+
+### Execution checklist
+- [ ] Inputs to inspect: whether a matching Nuxt UI component exists for the surface.
+- [ ] Minimal verification: the implementation uses the framework component when one fits.
+- [ ] Stop condition: the required behavior is genuinely outside the component model.
+
+### Rule ID: `ui-current-api-shape-not-lookalike`
+### Rule: Match the current Nuxt UI API shape, not a plausible lookalike
+### When to apply
+Using existing or newly added Nuxt UI components.
+
+### Wrong pattern
+Guessing old props, old slot names, or generic dialog and table APIs that only resemble the real component.
+
+### Recommended pattern
+Use the documented prop names, models, slots, and grouping patterns for the exact Nuxt UI component.
+
+### Nuxt-specific caveat
+Nuxt UI evals frequently expose “wrong but plausible” API memory rather than outright broken UI.
+
+### Execution checklist
+- [ ] Inputs to inspect: component props, slot API, and state model.
+- [ ] Minimal verification: component usage matches the expected API shape for the installed version.
+- [ ] Stop condition: the installed module intentionally wraps or replaces the upstream component API.
+
+### Rule ID: `ui-page-shells-belong-to-framework-components`
+### Rule: Use framework page-shell components when they exist
+### When to apply
+Docs pages, marketing shells, dashboards, or app page chrome where Nuxt UI supplies a page primitive.
+
+### Wrong pattern
+Hand-assembling repeated header and footer page chrome when a framework page-shell component exists.
+
+### Recommended pattern
+Prefer the page-shell component and compose around it.
+
+### Nuxt-specific caveat
+A raw HTML page can look polished while still being the wrong answer if the framework expects a Nuxt UI shell.
+
+### Execution checklist
+- [ ] Inputs to inspect: repeated page chrome, layout composition, and available Nuxt UI shell primitives.
+- [ ] Minimal verification: shared page chrome is expressed through the framework primitive when available.
+- [ ] Stop condition: the prompt explicitly requires bespoke shell markup.

package/nuxt-best-practices/rules/page-meta-head-layout.md

@@ -0,0 +1,58 @@
+## Page Meta, Head, and Layout
+
+### Rule ID: `page-define-page-meta-for-page-behavior`
+### Rule: Use `definePageMeta` for page behavior, not document metadata
+### When to apply
+Changing layout, middleware, route rules, page transitions, keepalive, or other page-level behavior.
+
+### Wrong pattern
+Using `useHead` or ad hoc component wiring for concerns that belong in page metadata.
+
+### Recommended pattern
+Use `definePageMeta` in page files for page behavior and routing-related options.
+
+### Nuxt-specific caveat
+`definePageMeta` is about how a page behaves inside the app, not what goes into the document head.
+
+### Execution checklist
+- [ ] Inputs to inspect: whether the change lives in a page file and affects app behavior rather than head tags.
+- [ ] Minimal verification: page behavior is expressed through page metadata instead of custom glue.
+- [ ] Stop condition: the change is not page-scoped.
+
+### Rule ID: `page-use-head-for-document-metadata`
+### Rule: Use `useHead` or `useSeoMeta` for title and meta tags
+### When to apply
+Changing page title, meta description, canonical URLs, social metadata, or structured head elements.
+
+### Wrong pattern
+Trying to set document metadata with `definePageMeta` or template markup.
+
+### Recommended pattern
+Use `useHead` for general document head state and `useSeoMeta` for SEO-focused metadata.
+
+### Nuxt-specific caveat
+Head metadata and page metadata are adjacent concepts but are not interchangeable.
+
+### Execution checklist
+- [ ] Inputs to inspect: the exact metadata surface being changed.
+- [ ] Minimal verification: head data is emitted through Nuxt head composables.
+- [ ] Stop condition: the task is about route behavior, layout, or middleware instead.
+
+### Rule ID: `page-layout-structure-belongs-in-layouts`
+### Rule: Put shared page chrome and structure in layouts or framework shells
+### When to apply
+Repeated headers, footers, navigation shells, or shared page structure across routes.
+
+### Wrong pattern
+Copying shell markup into pages or mixing layout concerns into unrelated components.
+
+### Recommended pattern
+Use layout files or framework-owned shell primitives for shared structure.
+
+### Nuxt-specific caveat
+Layout confusion often travels with `definePageMeta` vs `useHead` confusion, so resolve both surfaces together.
+
+### Execution checklist
+- [ ] Inputs to inspect: whether the structure is shared across pages and whether a layout already exists.
+- [ ] Minimal verification: shared shell concerns live in the layout layer, not duplicated page markup.
+- [ ] Stop condition: the structure is intentionally page-specific.

package/nuxt-best-practices/rules/performance-rendering.md

@@ -0,0 +1,77 @@
+## Performance and Rendering
+
+### Rule ID: `perf-use-nuxtlink-for-internal-nav`
+### Rule: Use `NuxtLink` for internal navigation
+### When to apply
+Creating or refactoring internal navigation links.
+
+### Wrong pattern
+Using raw `<a>` tags for internal routes without Nuxt link behavior.
+
+### Recommended pattern
+Use `NuxtLink` for internal routes and tune prefetch strategy when needed (`visible` vs `interaction`).
+
+### Nuxt-specific caveat
+`NuxtLink` carries built-in route-aware prefetching and defaults that reduce navigation latency.
+
+### Execution checklist
+- [ ] Inputs to inspect: internal links in pages/layout/components.
+- [ ] Minimal verification: internal links use `NuxtLink` and preserve semantics/accessibility.
+- [ ] Stop condition: link target is external or deliberately bypasses router.
+
+### Rule ID: `perf-match-route-rules-to-content-volatility`
+### Rule: Use route rules to match rendering strategy to content volatility
+### When to apply
+Pages with mixed static, stale-while-revalidate, ISR, or client-only requirements.
+
+### Wrong pattern
+Applying one rendering mode globally when route behavior differs.
+
+### Recommended pattern
+Set explicit `routeRules` per route family (`prerender`, `swr`, `isr`, `ssr: false`) based on freshness and SEO needs.
+
+### Nuxt-specific caveat
+Nuxt/Nitro route rules directly shape cache semantics and server behavior per route.
+
+### Execution checklist
+- [ ] Inputs to inspect: route patterns, freshness requirements, and SEO constraints.
+- [ ] Minimal verification: configured rules align with intended cache/render behavior.
+- [ ] Stop condition: deployment target cannot support required route rule semantics.
+
+### Rule ID: `perf-lazy-load-and-hydrate-intentionally`
+### Rule: Use lazy component loading and lazy hydration intentionally
+### When to apply
+Components not required for first meaningful paint or immediate interactivity.
+
+### Wrong pattern
+Hydrating all components eagerly on initial page load.
+
+### Recommended pattern
+Use `Lazy*` component imports and hydration triggers (for example `hydrate-on-visible`) for non-critical islands.
+
+### Nuxt-specific caveat
+Lazy hydration support exists in Nuxt and can materially reduce main-thread work on initial navigation.
+
+### Execution checklist
+- [ ] Inputs to inspect: above-the-fold criticality and interactive timing needs.
+- [ ] Minimal verification: non-critical UI defers code/hydration without breaking UX.
+- [ ] Stop condition: component must be immediately interactive for first render flow.
+
+### Rule ID: `perf-reduce-payload-and-asset-cost`
+### Rule: Reduce payload and asset cost before adding infra complexity
+### When to apply
+Performance regressions tied to response size, client JS, images, or third-party scripts.
+
+### Wrong pattern
+Adding caching layers first while shipping oversized payloads/assets.
+
+### Recommended pattern
+Trim async-data payload shape, optimize images/fonts/scripts with Nuxt-native tooling, and profile with DevTools + `nuxi analyze`.
+
+### Nuxt-specific caveat
+Nuxt Image, Nuxt Fonts, and Nuxt Scripts are designed to target LCP/CLS/INP regressions with Nuxt-aware defaults.
+
+### Execution checklist
+- [ ] Inputs to inspect: payload tab, bundle analysis, image/script/font loading paths.
+- [ ] Minimal verification: measurable reduction in transferred bytes or blocking work on critical path.
+- [ ] Stop condition: bottleneck is backend latency unrelated to client payload/asset behavior.

package/nuxt-best-practices/rules/plugins.md

@@ -0,0 +1,58 @@
+## Plugins and Runtime Boot
+
+### Rule ID: `plugin-use-composables-before-plugin`
+### Rule: Prefer composables/utilities before creating a plugin
+### When to apply
+Adding shared logic or helper functions used by limited parts of the app.
+
+### Wrong pattern
+Creating a global plugin for logic that can live in local composables/utilities.
+
+### Recommended pattern
+Use plugins only for true app-wide injection, app hooks, or framework integration boundaries.
+
+### Nuxt-specific caveat
+Every plugin participates in startup/hydration paths; unnecessary plugins add global boot cost.
+
+### Execution checklist
+- [ ] Inputs to inspect: plugin purpose, usage breadth, and required injection scope.
+- [ ] Minimal verification: plugin is justified by app-wide behavior, not convenience alone.
+- [ ] Stop condition: integration requires app-level hook/injection semantics.
+
+### Rule ID: `plugin-async-parallel-when-independent`
+### Rule: Run async plugins in parallel when they are independent
+### When to apply
+Multiple async plugins with no ordering dependency.
+
+### Wrong pattern
+Leaving independent async plugins serialized.
+
+### Recommended pattern
+Use object plugin syntax with `parallel: true`; define `dependsOn` only for real ordering constraints.
+
+### Nuxt-specific caveat
+Nuxt plugin runtime supports parallel execution and dependency-aware sequencing.
+
+### Execution checklist
+- [ ] Inputs to inspect: plugin async work and inter-plugin dependency graph.
+- [ ] Minimal verification: independent plugins run in parallel without race conditions.
+- [ ] Stop condition: plugin order is required for correctness.
+
+### Rule ID: `plugin-order-controls-only-when-necessary`
+### Rule: Use plugin ordering controls sparingly
+### When to apply
+You need deterministic plugin execution order.
+
+### Wrong pattern
+Using `order`/`enforce` aggressively to patch unclear plugin design.
+
+### Recommended pattern
+Keep default order first; use `dependsOn` for explicit dependency edges and reserve `order` for advanced edge cases.
+
+### Nuxt-specific caveat
+`order` overrides `enforce` and increases maintenance risk when plugin graphs evolve.
+
+### Execution checklist
+- [ ] Inputs to inspect: plugin metadata (`enforce`, `dependsOn`, `order`) and real dependency needs.
+- [ ] Minimal verification: ordering metadata is minimal and documented by dependency reason.
+- [ ] Stop condition: required order cannot be represented without broad global ordering hacks.

package/nuxt-best-practices/rules/server-routes-runtime-config.md

@@ -0,0 +1,58 @@
+## Server Routes, h3 Patterns, and Runtime Config
+
+### Rule ID: `server-validate-input-at-boundary`
+### Rule: Validate request input at handler boundaries
+### When to apply
+Creating or updating `server/api/*` routes, webhook handlers, or actions.
+
+### Wrong pattern
+Trusting payload shape and casting request body directly.
+
+### Recommended pattern
+Validate input at handler entry and return explicit HTTP errors on invalid data.
+
+### Nuxt-specific caveat
+Keep validation close to h3 handler entrypoints to avoid hidden assumptions.
+
+### Execution checklist
+- [ ] Inputs to inspect: new/edited handler params, body parsing, query usage.
+- [ ] Minimal verification: invalid payload returns explicit error status.
+- [ ] Stop condition: handler cannot define a stable input contract.
+
+### Rule ID: `server-runtime-config-public-minimal`
+### Rule: Keep runtime config exposure intentional
+### When to apply
+Adding env vars or endpoint values in `runtimeConfig`.
+
+### Wrong pattern
+Moving broad server configuration into `runtimeConfig.public`.
+
+### Recommended pattern
+Expose only the minimum public keys required by the client.
+
+### Nuxt-specific caveat
+Changes under `runtimeConfig.public` are effectively public API changes.
+
+### Execution checklist
+- [ ] Inputs to inspect: `nuxt.config` runtime config additions/changes.
+- [ ] Minimal verification: only intended public keys are exposed.
+- [ ] Stop condition: feature requires exposing secrets in public config.
+
+### Rule ID: `server-header-forwarding-allowlist`
+### Rule: Forward request headers intentionally
+### When to apply
+Proxying request context from SSR to internal or external API calls.
+
+### Wrong pattern
+Blindly forwarding all inbound headers to upstream services.
+
+### Recommended pattern
+Use `useFetch('/api/*')` for internal request-context propagation and explicit allowlists for external API calls.
+
+### Nuxt-specific caveat
+Relative `useFetch` calls on server use request-aware fetch behavior; external forwarding still requires explicit safety controls.
+
+### Execution checklist
+- [ ] Inputs to inspect: forwarded header sets and upstream destination type (internal vs external).
+- [ ] Minimal verification: only required headers are forwarded, with no unsafe pass-through.
+- [ ] Stop condition: upstream contract demands full raw header pass-through.

package/nuxt-best-practices/rules/verification-finish.md

@@ -0,0 +1,58 @@
+## Verification and Finish
+
+### Rule ID: `verify-check-the-intended-surface`
+### Rule: Verify the intended framework surface, not only the visible result
+### When to apply
+Before concluding a Nuxt change.
+
+### Wrong pattern
+Stopping once the UI looks correct or once one failing line was changed.
+
+### Recommended pattern
+Confirm that the final implementation uses the intended Nuxt, Nuxt Content, or Nuxt UI surface.
+
+### Nuxt-specific caveat
+Framework tasks often fail because the behavior is visibly fixed but implemented through the wrong abstraction.
+
+### Execution checklist
+- [ ] Inputs to inspect: the final primitive, composable, or component choice.
+- [ ] Minimal verification: the solution matches the framework-owned abstraction expected by the task.
+- [ ] Stop condition: the prompt explicitly asks for a framework-agnostic implementation.
+
+### Rule ID: `verify-second-surface-before-finish`
+### Rule: Check for a second required surface before finishing
+### When to apply
+Tasks involving errors, layout plus page behavior, or server/client boundaries.
+
+### Wrong pattern
+Editing the first obvious file and concluding the work without checking paired surfaces.
+
+### Recommended pattern
+Ask whether the change also needs a global/local or server/client counterpart, then verify both surfaces explicitly.
+
+### Nuxt-specific caveat
+Nuxt patterns often span more than one file or render surface, especially around errors and privileged data flow.
+
+### Execution checklist
+- [ ] Inputs to inspect: related files such as `app/error.vue`, local boundaries, server routes, client callers, layouts, and pages.
+- [ ] Minimal verification: both required surfaces are updated or explicitly ruled out.
+- [ ] Stop condition: the task is intentionally isolated to one surface.
+
+### Rule ID: `verify-version-sensitive-api-shapes`
+### Rule: Re-check version-sensitive API shapes before finalizing
+### When to apply
+Using components or module APIs that have plausible older alternatives.
+
+### Wrong pattern
+Trusting approximate memory for component props, slot names, or composable signatures.
+
+### Recommended pattern
+Re-check the installed skill or linked docs when an API shape looks close but uncertain.
+
+### Nuxt-specific caveat
+Version drift often shows up as “almost right” component or module usage that passes casual review but is wrong for the installed version.
+
+### Execution checklist
+- [ ] Inputs to inspect: wrapper links, installed skill guidance, and exact component or composable signature.
+- [ ] Minimal verification: current API names and state models match the installed version.
+- [ ] Stop condition: the local project intentionally wraps the upstream API with a different contract.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "nuxt-skill-hub",
+  "version": "0.0.1-beta.1",
+  "description": "Teach your AI agent the Nuxt way with best practices and module guidance.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxi/nuxt-skill-hub.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "files": [
+    "dist",
+    "nuxt-best-practices"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.3.1",
+    "automd": "^0.4.3",
+    "consola": "^3.4.0",
+    "giget": "^3.1.2",
+    "gray-matter": "^4.0.3",
+    "ofetch": "^1.5.0",
+    "pathe": "^2.0.0",
+    "pkg-types": "^2.3.0",
+    "unagent": "^0.0.8"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.1",
+    "@nuxt/eslint-config": "^1.15.1",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.1",
+    "@nuxt/test-utils": "^4.0.0",
+    "@nuxtjs/mdc": "^0.20.2",
+    "@types/node": "latest",
+    "@vue/test-utils": "^2.4.6",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.0.1",
+    "happy-dom": "^20.7.0",
+    "nuxt": "^4.3.1",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18",
+    "vue": "^3.5.29",
+    "vue-tsc": "^3.2.5"
+  },
+  "scripts": {
+    "dev": "pnpm --dir docs dev",
+    "dev:build": "nuxt-module-build build --stub --watch",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare",
+    "release": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run prepack && changelogen --release --push",
+    "lint": "eslint .",
+    "test": "pnpm run dev:prepare && vitest run && pnpm run test:pack",
+    "test:pack": "node ./scripts/check-packlist.mjs",
+    "test:watch": "vitest watch",
+    "test:types": "pnpm run dev:prepare && vue-tsc --noEmit",
+    "docs:typecheck": "pnpm --dir docs typecheck",
+    "typecheck": "pnpm run test:types && pnpm run docs:typecheck"
+  }
+}