Vue ui engineering

Vue Engineering Skill

For the Simplified Chinese reference, read references/zh-CN.md when the user communicates primarily in Chinese or requests Chinese output.

Purpose

Produce predictable Vue behavior with explicit reactivity, clear state ownership, stable rendering boundaries, and accessible component APIs.

When to Use

Use for Vue components, composables, forms, routing, Pinia or Vuex stores, data fetching, Nuxt SSR and hydration, or render performance.

Inputs

• Component behavior and states
• Vue and Nuxt versions, API style, and rendering model
• Existing component, composable, store, router, and test patterns
• Design and API contracts

Outputs

• Component and composable boundary plan
• Explicit state ownership and typed Vue implementation
• Behavior-focused tests and rendering notes

Workflow

1. Identify Vue and Nuxt versions, Options or Composition API conventions, router, rendering mode, style system, and test stack.
2. Search for equivalent components, composables, stores, routes, data-fetching utilities, and tests.
3. Assign each state value to one owner: parent props, local reactive state, URL, store, or server cache.
4. Design typed props, emits, models, slots, and exposed interfaces while preserving one-way data flow.
5. Use computed values for pure derivation. Use watchers only for external synchronization, asynchronous orchestration, or imperative integration, and clean up stale work.
6. Preserve reactive connections. Copy props or store state into local state only for an intentional editable draft with an explicit synchronization contract.
7. Extract composables when ownership, lifecycle, side effects, and reuse boundaries are clear; avoid hidden singleton state.
8. Add behavior-focused tests and validate SSR, hydration, keyboard behavior, and reduced motion where relevant.

Decision Tree

flowchart TD
  A[New Vue state] --> B{Controlled by a parent}
  B -->|Yes| C[Props plus emits or v-model]
  B -->|No| D{Shareable in the URL}
  D -->|Yes| E[Router params or query]
  D -->|No| F{Owned by the server}
  F -->|Yes| G[Framework data or query cache]
  F -->|No| H{Shared across distant consumers}
  H -->|Yes| I[Existing store pattern]
  H -->|No| J[Local ref or reactive state]

Checklist

• Vue and Nuxt version-specific behavior is confirmed.
• Props, emits, models, slots, and exposed APIs are typed.
• Derived values use computed state instead of synchronized copies.
• Watchers have an external purpose, bounded dependencies, and cleanup.
• Stores and composables have explicit ownership and lifecycle.
• List keys are stable and semantic.
• SSR output is deterministic and browser-only APIs are guarded.
• Tests use user-visible roles, names, and interactions.

Constraints

• MUST follow the repository's Vue version, API style, state library, and SFC conventions.
• MUST NOT mutate props or bypass the component's declared event contract.
• SHOULD derive pure values with computed state instead of synchronizing duplicate refs with watchers.
• SHOULD NOT introduce a global store or singleton composable for component-local state.
• MUST clean up listeners, timers, subscriptions, and stale asynchronous work.
• MUST NOT suppress hydration warnings instead of fixing nondeterministic output or an incorrect client boundary.

Examples

Good: derive filteredItems with a computed value from the source collection and query.

Bad: copy filteredItems into a ref and keep it synchronized with a deep watcher.

Anti-patterns

• Giant SFCs combining data access, business rules, state orchestration, and presentation
• Destructuring reactive sources without confirming reactivity is preserved for the project version
• Broad deep watchers used as a substitute for explicit state ownership
• Stores used as event buses or dumping grounds for local state
• Array-index keys for reorderable lists
• Browser globals accessed during SSR without an explicit client boundary