AgentSkillsCN

vue-best-practices

全面的 Vue 3 开发最佳实践、TypeScript 配置、工具故障排除、测试模式和 Composition API 注意事项。涵盖 vue-tsc、Volar、Vite 配置、Vue Router 类型、组件测试、响应式模式和 SFC 特性。适用于 Vue 3 + TypeScript 项目、调试构建错误、编写测试或遵循最佳实践。

SKILL.md
--- frontmatter
name: vue-best-practices
description: Comprehensive Vue 3 development best practices, TypeScript configuration, tooling troubleshooting, testing patterns, and composition API gotchas. Covers vue-tsc, Volar, Vite configuration, Vue Router typing, component testing, reactivity patterns, and SFC features. Use when working with Vue 3 + TypeScript projects, debugging build errors, writing tests, or following best practices.
license: MIT
metadata:
  author: hyf0
  version: "5.0.0"

Vue Best Practices

Comprehensive development guidelines, TypeScript configuration, and best practices for Vue 3 applications.

When to Apply

  • •Setting up or configuring Vue 3 + TypeScript projects
  • •Debugging type checking issues with vue-tsc
  • •Fixing IDE/editor integration with Volar
  • •Configuring Vite for Vue projects
  • •Working with Vue Router typed routes
  • •Writing component tests with Vitest
  • •Using Composition API patterns
  • •Working with defineModel, defineProps, defineExpose
  • •Writing reusable composables

Capability Rules

Rules that enable AI to solve problems it cannot solve without the skill.

Type Checking

RuleImpactDescription
vue-tsc-strict-templatesHIGHEnable strict template checking to catch undefined components
vue-define-model-genericsHIGHFix vue-tsc errors when using defineModel with generic components

vueCompilerOptions Settings

RuleImpactDescription
fallthrough-attributesHIGHType-check fallthrough attributes on wrapper components
strict-css-modulesMEDIUMCatch typos in CSS module class names at compile time
data-attributes-configMEDIUMAllow data-* attributes with strictTemplates enabled

Tooling & Configuration

RuleImpactDescription
vue-tsc-typescript-compatibilityHIGHFix vue-tsc and TypeScript version incompatibility issues
volar-3-breaking-changesHIGHFix editor integration after Volar/vue-language-server 3.0 upgrade
module-resolution-bundlerHIGHFix "Cannot find module" errors after @vue/tsconfig upgrade
unplugin-auto-import-conflictsHIGHFix component types resolving as any with unplugin conflicts
codeactions-save-performanceHIGHFix 30-60 second save delays in large Vue projects

Vite Configuration

RuleImpactDescription
path-alias-vue-sfcHIGHFix resolve.alias failures in Vue SFC files
duplicate-plugin-detectionMEDIUMDetect and fix duplicate Vue plugin registration

Component Patterns

RuleImpactDescription
use-template-ref-genericsMEDIUMFix incorrect type inference for refs to generic components
define-model-update-eventMEDIUMFix runtime errors from unexpected undefined in model updates
with-defaults-union-typesMEDIUMFix incorrect default value behavior with union type props
verbatim-module-syntaxMEDIUMFix Vite dev server errors with type-only imports
deep-watch-numericMEDIUMEnable efficient array mutation watching with Vue 3.5+ numeric deep

Template Patterns

RuleImpactDescription
vue-directive-commentsHIGHControl template type checking with @vue-ignore, @vue-skip directives

SFC Patterns

RuleImpactDescription
script-setup-jsdocMEDIUMAdd JSDoc documentation to script setup components

Vue Router

RuleImpactDescription
vue-router-typed-paramsMEDIUMFix route params type narrowing with unplugin-vue-router

Testing Patterns

RuleImpactDescription
teleport-testingHIGHTest teleported content (modals, tooltips)

TypeScript Patterns

RuleImpactDescription
vueuse-emits-conflictMEDIUMFix $emit type conflicts with VueUse element composables

Efficiency Rules

Rules that help AI solve problems more effectively and consistently.

Vite Configuration

RuleImpactDescription
runtime-env-variablesHIGHImplement runtime environment variables for multi-env deployments
hmr-vue-ssrMEDIUMFix HMR issues in Vue SSR applications

Component Patterns

RuleImpactDescription
define-expose-typesMEDIUMFix "Property does not exist" errors when accessing exposed methods
provide-inject-typesMEDIUMEnable type-safe dependency injection with InjectionKey

Vue Router

RuleImpactDescription
route-meta-typesHIGHExtend RouteMeta interface for type-safe metadata
scroll-behavior-typesMEDIUMProperly type scrollBehavior function
dynamic-routes-typingMEDIUMType-safe dynamic route configuration

Testing Patterns

RuleImpactDescription
suspense-testingHIGHTest async components with Suspense properly
pinia-store-mockingHIGHMock Pinia stores correctly with Vitest
router-mockingHIGHMock Vue Router with useRoute and useRouter
vue-test-utils-typesMEDIUMFix wrapper.vm property access types in Vue Test Utils

Composition API Patterns

RuleImpactDescription
reactive-destructuringHIGHAvoid reactivity loss when destructuring reactive objects
composable-cleanupHIGHPrevent memory leaks in composables with proper cleanup
ref-unwrappingMEDIUMUnderstand ref auto-unwrapping in reactive objects
watcheffect-trackingMEDIUMFix conditional dependency tracking in watchEffect

SFC Patterns

RuleImpactDescription
script-setup-patternsHIGHBest practices for script setup syntax
css-v-bindMEDIUMSafely use reactive values in CSS

TypeScript Patterns

RuleImpactDescription
component-type-helpersHIGHExtract component prop and emit types
event-handler-typingMEDIUMType event handlers correctly

Reference