Vue Optimizer

Audit a Vue 3 codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Vue's performance is mostly decided by reactivity granularity, component boundaries, list keys and what ships to the client; changing those can alter behavior, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the root (package.json with vue, vite.config.*). Record: Vue version (3.5 stable; 3.6 RC/Vapor opt-in), Vite/Rolldown, Vue Router 5 vs 4, Pinia 4 vs 3/Vuex, TypeScript/vue-tsc, test runner, and whether the app is SPA, SSR, or SSG. For Nuxt, hand off to skills/web/nuxt.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, vite.config.*, .env*, and .vue/.ts/.js sources for version/compat drift, missing Vue plugin, v-for keys, v-if+v-for, v-html/XSS, store destructuring, watcher/listener leaks, route eager imports, SSR hazards and bundle config, with file:line evidence. Use --json to post-process.
• Classify the pain: slow first load (bundle/assets), slow interactions (reactivity/re-renders), large lists, memory growth (watchers/listeners), SSR/hydration, forms/a11y, or migration. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (vite build, vite preview, bundle visualizer, Vue DevTools, Lighthouse).

2. Audit

The script finds cheap leads; you find the rest by reading. Read vite.config.*, src/main.ts, src/App.vue, the router and store, and the 3-5 hottest components. Load only what applies:

Measure, never guess. Build for production (vite build) and serve vite preview (or the SSR server), then measure that. Dev mode and a single warm interaction are not evidence. Record route/entry JS and CSS, chunk graph, LCP/INP/CLS, Vue DevTools render counts, memory/listener counts and hydration warnings.

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

3. Report

Fill assets/report-template.md, save it as VUE_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 -- stable :key, split v-if+v-for, replace template method calls with computed, add shallowRef/markRaw for big immutable data, use storeToRefs, stop deep-watching large objects, add defineAsyncComponent/lazy routes, add loading/dimensions to images, fix labels/button types, add bundle budgets. Low risk.
2. Structural -- split god components, virtualize large lists, move data fetching to route loaders/composables with cancellation, adopt Pinia setup stores and selectors, add SSR/SSG where it fits, configure Rolldown chunk groups, prune UI/icon libraries. Name each behavior change.
3. Heavy -- Vue 2 → 3, Vue 3.5 → 3.6/Vapor (RC), Vue Router 4 → 5 file-based routing, Pinia 3 → 4, Vite 7 → 8, SSR architecture, design-system extraction. 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: vue-tsc --noEmit, lint, tests, vite build, and the affected route/profile. A break must trace to one change. Do not mix a major-version migration or Vapor adoption with optimization edits. If a change alters public props/emits, routing/data flow, SSR boundaries, or store contracts, stop and ask.

6. Verify and wrap up

Re-measure the same routes and interactions: entry/route JS and CSS, chunk sizes, Vue DevTools render counts, LCP/INP/CLS, memory/listener counts, hydration warnings, test time. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Reactivity is fine-grained by design. Vue tracks property reads; the cost appears when you make whole objects deeply reactive, deep-watch large trees, or re-render large component subtrees.
• Keys decide list identity. A stable :key preserves state and avoids DOM churn; index keys break reorder/insert/delete flows.
• shallowRef is the large-data tool. Replace the array/value instead of mutating thousands of nested properties; use markRaw for non-reactive instances.
• Computed is the template cache. Move filtering/sorting/formatting out of templates and methods; avoid side effects in computed.
• Pinia state is not automatically reactive through destructuring. Use storeToRefs for state/getters and keep actions on the store.
• Routes are bundle boundaries. component: () => import(...) keeps a view out of the entry; static imports negate it.
• Vite 8 uses Rolldown and Oxc. Prefer rolldownOptions/oxc; rollupOptions/esbuild are compatibility paths, not the target.
• SSR is a state and markup contract. Per-request state, useSSRContext, onServerPrefetch and matching client markup decide whether hydration works.
• Vapor Mode is an RC, not a default. Vue 3.6/Vapor is opt-in and partial; measure a single page before trusting it.
• Docs move. Check vuejs.org, router.vuejs.org, pinia.vuejs.org and vite.dev for the installed major, not memory.