Nuxt Optimizer

Audit a Nuxt codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Nuxt's performance is mostly decided by rendering mode, the SSR payload, caching rules and server handlers; changing those can silently change freshness or leak user data, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the root (package.json with nuxt, nuxt.config.ts). Record: Nuxt version (4.6 current; 5 behind future.compatibilityVersion), Vue/Vite, rendering (universal, SPA, hybrid), Nitro preset, modules (image/fonts/scripts/content/ui), data layer, auth/session, and whether app/ or legacy root dirs are used.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, nuxt.config.*, app/, server/ and .vue/.ts sources for $fetch in setup, payload bloat, route-rule/cache mistakes, server/client leakage, raw images, XSS and bundle risks, with file:line evidence. Use --json to post-process.
• Classify the pain: slow TTFB (SSR/data/cache), large payload/hydration, slow client navigation, slow API/server routes, build/deploy, or code health/migration. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (nuxt build, nuxt preview, nuxt analyze, DevTools, Lighthouse).

2. Audit

The script finds cheap leads; you find the rest by reading. Read nuxt.config.ts, app/app.vue, the 3-5 hot pages, their composables, and the server routes they call. Load only what applies:

Measure, never guess. Run nuxt build and nuxt preview (or the Nitro preset's server), then measure that. Dev mode and a single warm navigation are not evidence. Record SSR TTFB, payload size, query/API timings, route JS, hydration and LCP/CLS.

Mark each finding Confirmed (build output, network/profiler, code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as NUXT_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- replace setup $fetch with useFetch/useAsyncData, add keys/pick/transform, parallelize independent requests, lazy non-critical data, add NuxtImg/fonts, lazy components, route rules for static pages, fix cache keys/headers. Low risk.
2. Structural -- choose SSR/ISR/SWR per route, move auth/data into server routes, split slow handlers, cache expensive functions, reduce payload/DTOs, add lazy hydration/noScripts for static pages, restructure modules. Name each behavior change.
3. Heavy -- Nuxt 4 → 5 compatibility migration, Nuxt 3 → 4 layout, Nitro preset/edge change, module replacements, server architecture. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: nuxt typecheck, lint, tests, nuxt build. A break must trace to one change. Do not mix a Nuxt major/compatibility migration with optimization edits. If a change makes a response cacheable that contains user data, or moves secret/server code toward the client, stop and ask.

6. Verify and wrap up

Re-measure the same routes: SSR TTFB, payload/HTML size, route JS, API/query latency, navigation, LCP/INP/CLS, cache hit rate. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• The payload is the contract. useFetch/useAsyncData serialize server data into HTML for hydration; $fetch in setup fetches twice.
• Keys and freshness are correctness. Same key means shared data; explicit keys, pick/transform, watch, getCachedData and clearNuxtData decide freshness and memory.
• One rendering mode per route. Use route rules for prerender/ISR/SWR/SSR:false instead of a global compromise.
• Never cache per-user data in a shared layer. Cache keys must include user/tenant/locale when the output depends on them.
• Server code stays in server/. Never import Vue app code into Nitro handlers or server code into the app.
• Runtime config, not process.env, in app code. Only runtimeConfig.public reaches the browser; secrets stay private.
• Ship less JS by default. Lazy components, lazy hydration, noScripts, NuxtImg/Fonts/Scripts, and module pruning beat micro-optimizations.
• Payload size beats extra requests. pick/transform/DTOs and serialize: false for non-critical data keep HTML small.
• Nuxt 5 is opt-in. compatibilityVersion: 5 changes data-fetching semantics; treat it as a migration.
• Docs move. Check nuxt.com for the installed version (4.x vs 5.x compat), not memory.