nuxt-domain-delivery

name: nuxt-domain-delivery namespace: stacks/nuxt description: 'Use WHEN implementing or reviewing Nuxt pages, layouts, middleware, server routes, Nitro behavior, data fetching, runtime config, SSR/hydration, modules, SEO, deployment, or rollback work. TO deliver stack-specific production changes with framework-native practices, verification evidence, and rollback discipline.' allowed-tools: - Read - Grep - Glob - Bash phase: implementation prerequisites: [] emits-artifact: nuxt-domain-delivery-report confidence-rubric: confidence-rubrics/agent-delivery.yaml gate-on-exit: true version: 1.1 last-verified: 2026-06-06T00:00:00.000Z

Nuxt Domain Delivery

Overview

Nuxt Domain Delivery protects the seam between Vue and Nitro: pages/layouts, middleware, server routes, SSR payloads, useFetch/useAsyncData, runtime config, modules, SEO, hydration, deployment presets, and rollback. It turns a Nuxt change into a render-mode-aware full-stack slice.

When to Use

Use for Nuxt pages, layouts, route middleware, server/api, server/routes, Nitro handlers/plugins, useFetch, $fetch, useAsyncData, useState, runtime config, modules, routeRules, SSR/SSG/ISR/CSR behavior, hydration mismatches, SEO/head, and deployment readiness.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: read local source first, preserve evidence, follow Nuxt conventions, verify before completion claims, and cap confidence when routeRules, runtime config, server validation, hydration, or deployment is not proven.

Step 0 - Read source of truth

Read the user request, AGENTS.md, task graph item, and owned write set.
Inspect package.json, nuxt.config.*, pages/ or app/pages/, layouts/, middleware/, server/, composables/, stores/, modules, tests, and deploy scripts.
Search for routeRules, runtimeConfig, nitro, useFetch, useAsyncData, $fetch, useState, defineEventHandler, defineNuxtRouteMiddleware, and existing SEO helpers.
Use CodeGraph for unfamiliar route/server surfaces and CodeGraph or symbol search before changing exported composables, handlers, middleware, stores, or module config.

When not to use

Do not use when the task is generic planning, product shaping, design, or release governance and no Nuxt implementation or review boundary exists.
Do not use when another stack, database, security, deployment, or API owner has the primary decision; hand off to that specialist and keep the Nuxt part scoped.
Do not use to justify dependency swaps, broad rewrites, heavy test runs during graph execution, or mixed old-plan scope without explicit approval.

Decision tree

User-visible route? -> pages/app/pages .vue with declared render mode from routeRules.
Shared shell? -> layouts/<name>.vue plus definePageMeta usage.
Navigation policy? -> named/global route middleware, mirrored server auth where needed.
HTTP/server logic? -> server/api or server/routes with validated body/query/params.
Page data for SSR/hydration? -> useFetch/useAsyncData with explicit stable key.
Client event after hydration? -> $fetch inside handler/watch, not top-level page data.
Shared SSR-safe state? -> useState('<feature>:<key>'), never anonymous/global keys.
Config/env? -> runtimeConfig private vs public; never process.env in app code.
SEO/public content? -> useSeoMeta/useHead/server route sitemap/robots as appropriate.
Deployment/runtime affected? -> Nitro preset/deps/routeRules/rollback documented.

Procedure

Define the slice: route/server endpoint/middleware/module, render mode, data source, runtime config, verification command, and rollback path.
Confirm render mode. Read routeRules and prior decisions; do not silently choose SSR/CSR/ISR for a route with product, SEO, auth, or cache impact.
Place files by Nuxt convention. Use pages for routes, layouts for shells, middleware for navigation, composables for reusable client/server-safe logic, stores for shared state, and server/ for server-only APIs/plugins.
Design data fetching. Use useFetch for SSR-hydrated HTTP reads, useAsyncData for non-fetch async reads, $fetch for event-driven client calls or server-to-server calls, and explicit keys/defaults/transforms for deterministic hydration.
Validate server routes. Every server/api body/query/param path uses a schema or equivalent narrowing, enforces auth/authz when needed, returns typed errors, and avoids leaking stack traces or secrets.
Handle runtime config. Add values through runtimeConfig, keep secrets out of .public, type config where the project supports it, and consume config through useRuntimeConfig() in the correct context.
Protect SSR/hydration. Avoid browser-only APIs during SSR, gate client-only widgets with .client.vue or <ClientOnly>, use stable useState keys, and test for hydration warnings on changed routes.
Curate modules. Prefer existing modules, justify new modules by runtime value, pin versions through the package manager, and note build/runtime side effects and rollback.
Implement SEO and head output. Use useSeoMeta, useHead, route metadata, canonical links, Open Graph, robots/sitemap handlers, and server-rendered content for crawlable pages.
Plan deployment and rollback. Name Nitro preset assumptions, edge/Node API compatibility, env/config needs, routeRules/cache effects, preview deploy, previous build redeploy, and feature flag or route disable path.
Write focused tests first when behavior changes: page render, server route validation/auth, middleware redirect, composable data shape, SEO output, and hydration-sensitive state.
Repair loop: localize to routeRules, fetch primitive, server validation, runtime config, hydration, module, or Nitro build; fix narrowly and rerun the same scoped command. Escalate architecture changes.
Read the source artifact, owned file paths, graph/task scope, and current project convention; record the evidence path, command, receipt, or runtime state that proves the starting point.
If required source, owner, dependency, runtime boundary, or approval is missing, stop and return BLOCKED with the missing field, impacted artifact, and next action instead of guessing.
After edits or reviewer findings, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, artifact path, confidence, and remaining blocker before completion.

Worked example

Add /catalog/[slug] with server API data:

routeRules says catalog is ISR/SWR; the page uses useFetch with key catalog:item:<slug>, default, and transform to a view model.
server/api/catalog/[slug].get.ts validates slug, returns only public DTO fields, and maps not-found to a typed 404 response.
SEO is emitted with useSeoMeta from the DTO and canonical URL.
Rollback is previous build redeploy plus routeRules/cache purge for catalog pages if stale bad payloads were generated.

Good and bad delivery paths

Good delivery path: deliver through routeRules, useFetch with stable key/default/transform, Nitro server API validation, public DTO shaping, SEO metadata, and cache purge strategy. Runtime-specific tests include server API validation and typed 404s, page/load behavior for SSR or SWR, routeRules/Nitro cache behavior, hydration with transformed data, SEO output, and Playwright or Nuxt test smoke for navigation. Rollback redeploys the previous build, purges routeRules/cache entries, and disables the server route if needed. Failure boundaries are invalid slug, private-field leakage, stale SWR payload, hydration mismatch, not-found mapping, and server API failure.

Bad unsafe path: fetch catalog data only in the browser with a private token, skip DTO validation, rely on default cache behavior, and test a component in isolation. That path has no runtime-specific tests for the changed stack surface, no concrete rollback beyond hope or manual cleanup, and weak failure boundaries for invalid slug, private-field leakage, stale SWR payload, hydration mismatch, not-found mapping, and server API failure.

Common rationalizations

"Auto-generated useFetch keys are good enough" fails when call sites move, multiple instances share an endpoint, or hydration dedupe changes.
"This API is internal" fails because server/api still accepts hostile HTTP input unless protected and validated.
"Put it in runtimeConfig.public so the client can read it" fails when the value is a credential, tenant secret, or private endpoint.

Red flags

$fetch appears at top level of a page for data needed in SSR HTML.
useFetch or useAsyncData lacks a stable explicit key.
useState key is generic such as user, items, or data.
runtimeConfig.public contains anything that would be unsafe in a README.
Server route reads raw body without schema validation.
Hydration warning is dismissed as harmless.
Nitro preset or module addition has no rollback plan.

Checklist

Route render mode and routeRules are known or escalated.
Data-fetch primitive matches SSR/client/event behavior.
Server routes validate input and enforce auth/authz when needed.
Runtime config keeps secrets private and is consumed through Nuxt APIs.
SSR/hydration risks are handled with stable keys and client-only boundaries.
SEO metadata is server-rendered for crawlable routes.
Deployment preset, module impact, cache behavior, and rollback are named.

Failure modes

The Nuxt specialist applies a generic pattern and misses framework-owned lifecycle, typing, permission, migration, cache, or deployment behavior.
The worker mixes a new graph task with stale plan scope and creates a larger review surface than the MVP flow needs.
The task closes with prose only: no source evidence, no scoped command or final-gate deferral, no rollback, and no next action for blockers.

Output contract

status: PASS, BLOCKED, PARTIAL, or DEFERRED.
slice: pages, layouts, middleware, server routes, modules, config changed.
renderMode: SSR/SSG/ISR/CSR/edge decision and source evidence.
dataFetching: useFetch/useAsyncData/$fetch choices, keys, defaults, transform, error handling.
serverAndConfig: validation, auth/authz, runtimeConfig public/private proof.
hydrationAndSEO: hydration risk checks, client-only boundaries, metadata.
tests: scoped commands and cases, or final-gate deferral reason.
deploymentRollback: Nitro preset, routeRules/cache, env, flag/revert path.
confidence: score with caps from missing render/config/hydration/build proof.

Guard rails

Do not implement Nuxt changes from a generic skill when a stack-specific owner, migration path, or runtime boundary is missing.
Avoid broad rewrites, dependency swaps, large test suites, or speculative architecture changes during fast MVP execution.
Reject work that skips source search, rollback naming, or scoped verification for the changed slice.
Stop when local project conventions, version constraints, permissions, data ownership, or deployment target are unknown.

Verification

Run the scoped command required by the active graph when policy allows, such as nuxi typecheck, vitest run <path>, lint, nuxi build, or @nuxt/test-utils route/server tests.
Verify new useFetch/useAsyncData calls have stable keys and error states.
Verify server routes reject malformed input and unauthorized access.
Verify runtime config public/private split and absence of hydration warnings.
Verify SEO output in SSR HTML for crawlable pages.
If any scoped check fails or new evidence appears, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, blockers, and final-gate deferrals before claiming completion.

Supporting references

Use local support files through progressive disclosure; keep the main SKILL.md as the operating contract and load deeper resources only when the active task needs them:

Read references/practice-pack.md when nuxt-domain-delivery needs deeper practice guidance, source evidence anchors, risk checks, or a final checklist beyond the core procedure.
Run scripts/self-check.mjs --check --json after editing this nuxt-domain-delivery resource tree or before claiming deterministic support-file readiness; use --help for options and --dry-run for read-only preview semantics.
Use evals/regression.json when calibrating nuxt-domain-delivery trigger boundaries, happy-path/failure-path coverage, boundary rollback behavior, or resource-tree regressions.
Open examples/workflow.md when a concrete nuxt-domain-delivery workflow example is needed for sequencing, evidence selection, or anti-example comparison.
Use templates/output-contract.md when emitting nuxt-domain-delivery-report so status, evidence, confidence, blockers, risks, rollback, and nextAction stay consistent.

supervibe:vue-domain-delivery
supervibe:frontend-ui-engineering
supervibe:auth-flow-design
supervibe:tdd
supervibe:code-search
supervibe:verification