michaelalber/vue-architecture-checklist

Vue Architecture Checklist

"A checklist cannot fly a plane, but a pilot cannot fly safely without one." — Atul Gawande

Core Philosophy

Shared across the dotnet / python / php / rust / react / vue architecture checklists — same values, language-specific checks.

Grounding note: the knowledge base has Vue 2/3 corpus under collection="javascript" (alongside TS/JS idioms) and collection="ui_ux" for accessibility, collection="internal" for architecture standards; cite vuejs.org as the primary Vue authority. Never invent a vue collection.

| # | Value | What it means | |---|-------|---------------| | 1 | Detect before judge | Determine Vue version / API style (Options vs Composition) / bundler / TS / state lib before applying any item; context decides what is idiomatic. | | 2 | Evidence over opinion | Every finding cites file:line and the offending pattern. "Reactivity is broken" is not a finding; "features/cart/CartSummary.vue:18 destructures const { total } = props, losing reactivity" is. | | 3 | Feature cohesion | Organized by feature, not by technical type (components/, composables/, utils/ dumping grounds). Cross-feature imports are a violation. | | 4 | Dependencies point inward | Components depend on composables/services, not the reverse; data-fetching is isolated from presentation. Boundaries are explicit via barrels. | | 5 | Composition API honors reactivity | ref/reactive unwrapped correctly; no destructuring reactive() (loses reactivity — use toRefs); watch/watchEffect dependency lists complete; watchers/effects clean up. | | 6 | Config & secrets hygiene | No secrets in client bundles; only intentionally-public VITE_/VUE_APP_ values exposed; config injected, not hardcoded. | | 7 | Version awareness | Recommendations gated to the detected Vue version; never suggest an API that does not exist there (e.g. <script setup> on Vue 2 without the Composition API plugin). | | 8 | Tests gate change | Untested components/composables are a finding; high-risk interactive components without Vue Testing Library tests are prioritized. | | 9 | Graded, actionable output | A letter grade (A–F) from counted findings, plus prioritized, version-correct recommendations. |

Workflow

Shared skeleton: DETECT → SCAN → REPORT → RECOMMEND.

DETECT     Vue version (package.json `vue`), API style (Options vs `<script setup>`/Composition),
           bundler (Vite/Vue CLI/Nuxt), TypeScript (tsconfig + strict), state library
           (Pinia/Vuex/none), router (vue-router). Record findings; version/style changes what
           is idiomatic.

SCAN       Run the Vue Checklist below section by section. Gather evidence with tooling:
             npx eslint . --max-warnings 0          # baseline — incl. eslint-plugin-vue
             npx vue-tsc --noEmit                    # type errors gate the review
             npx knip                                # dead code / unused exports / deps
             grep -rn "watchEffect\|watch(" src/ | wc -l   # watcher surface to audit
           Every violation becomes a finding with file:line and a severity (critical/high/medium/low).

REPORT     Emit the graded report (Output Template). Grade = function of counted findings.

RECOMMEND  Prioritize: critical → quick wins → modernization. Version-gate every recommendation.

Vue Checklist (language-specific)

| # | Check | Severity | |---|-------|----------| | 1 | Reactivity discipline — no destructuring reactive() without toRefs; ref unwrapped correctly in templates vs script; no reassigning a reactive() object wholesale | Critical | | 2 | Watcher/lifecycle correctness — complete watch dependency sources (no implicit-stale closures); cleanup registered for subscriptions/timers in onUnmounted; no derived state recomputed that belongs in a computed | High | | 3 | Component cohesion — one responsibility per SFC; container/presentational separation where it earns it; no 400-line god components | Medium | | 4 | State placement — state lives at the lowest common owner; no prop-drilling past ~3 levels (lift to provide/inject or a Pinia store); server state in a query layer, not ref+onMounted fetch | High | | 5 | Render performance — stable v-for :key (never array index for dynamic lists); computed preferred over methods for derived values; v-once/v-memo only where a measured re-render warrants it | Medium | | 6 | Type safety — tsconfig strict: true; <script setup lang="ts"> with typed defineProps/defineEmits; no any without justification | High | | 7 | Accessibility — semantic elements over div soup; interactive elements keyboard-reachable; labels/alt/ARIA where needed; eslint-plugin-vuejs-accessibility clean | High | | 8 | Boundary & dep hygiene — no cross-feature deep imports; data-fetching isolated from presentation; error handling around async UI (onErrorCaptured/app.config.errorHandler); bundle/dep weight justified | Medium |

ESLint config: eslint configuration. Full section-by-section list (with the reactivity & watcher audit table): review checklist.

State Block

<arch-checklist-state>
language: vue
mode: DETECT | SCAN | REPORT | RECOMMEND | COMPLETE
detected: [vue-version | api-style | bundler | ts:strict/loose | state-lib | tests:yes/no]
issues_found: [critical:N high:N medium:N low:N]
last_action: [what was just done]
next_action: [what should happen next]
</arch-checklist-state>

Output Template

Shared across all architecture checklists.

## Architecture Checklist: [app/package] (Vue)
**Vue**: [3.4] | **API**: [Options/Composition] | **Bundler**: [Vite/Vue CLI/Nuxt] | **TS**: [strict/loose/none] | **State**: [Pinia/Vuex/none] | **Tests**: [yes/no]

| Section | Pass | Fail | Warn |
|---------|------|------|------|
| Reactivity / Watchers / Cohesion / State / Render / Types / a11y / Boundaries | … | … | … |

### Grade: [A–F]
Grading: **A** 0 crit/0 high/≤3 med · **B** 0 crit/≤2 high · **C** 0 crit, gaps in one area ·
**D** 1+ crit · **F** fundamental problems (broken reactivity throughout, `any` everywhere, no a11y, server state in ad-hoc fetch everywhere).

| Severity | Location | Finding | Recommendation |
|----------|----------|---------|----------------|
| CRITICAL | file:line | [pattern] | [version-gated fix] |

**Reactivity/watcher audit**: | location | issue | dep source | cleanup | risk |
**Quick wins**: [low-effort, high-impact] · **Modernization**: [larger items with effort estimate]

AI Discipline Rules

• Lint + types must pass first. eslint --max-warnings 0 and vue-tsc --noEmit are the baseline; report failures before the architectural checklist.
• Evidence or it is not a finding. Cite file:line; show the eslint/grep output. Never grade on vibes.
• Version-gate recommendations. Do not suggest Vue 3-only APIs (<script setup>, Teleport, Suspense) for a Vue 2 codebase without the Composition API bridge.
• Architecture, not security. XSS, secret leakage, and dependency CVEs belong to vue-security-review — note them and route there.

Integration with Other Skills

• architecture-review — When the grade is D/F, escalate to the Socratic critic: this checklist finds what is wrong; architecture-review builds why.
• vue-security-review — Companion for the security dimension (XSS, bundle secrets, npm audit).
• vue-feature-slice — Correct-pattern reference when the checklist flags structural/cross-feature violations.
• vue-modernization-analyzer — When findings cluster around legacy patterns (Options API sprawl, Vue CLI), route to the modernization plan.
• tdd — Methodology for adding the missing tests the checklist flags, and for driving any refactor.
• dotnet / python / php / rust / react-architecture-checklist — Sibling skills sharing this exact Core Values + workflow + output.